Indicator

Fathom Imbalances

Stacked buyer and seller imbalances, turned into zones.

At a glance

Identifier
imbalances
Objects received
zone
Historical cost
1 compute unit per trade

What the indicator shows

  • An imbalance is a price level where one side overwhelms the other in the bar’s footprint, that is its bid and ask volume price by price. mode chooses how the two sides are compared, and minimumPercent how strongly one side must dominate.
  • When at least consecutive adjacent levels are imbalanced on the same side, they are called stacked imbalances: the indicator turns them into a zone. The footprint is not published; only the resulting zone is, when the bar closes.
  • A buy zone marks where buyers dominated across those levels; a sell zone, where sellers dominated. On the Fathom chart, buy zones are blue and sell zones coral.
  • The zone extends to the right while it is active. With triggeredZones, a retest zone (triggered: true) takes over after triggering.

How to use it

  • Price often comes back to these zones: a buy zone then acts as support, a sell zone as resistance.
  • A close on the other side triggers the zone: the level gave way. The retest zone follows that broken level, which can then play the opposite role.
  • Raise consecutive to keep only the clearest imbalances.

How to read and draw it

  • mode chooses how the buying and selling volume of the bar’s price levels are compared (see the parameter); groupTicks sets the size of those levels. Raising minimumPercent, minimumVolume or consecutive keeps only the clearest imbalances: fewer zones. includeZero also counts the levels where one side traded nothing.
  • With delta-percentage, minimumPercent must be given, at most 100: the default is rejected in this mode.
  • A zone spans from low, its bottom, to high, its top, extraTicks ticks of padding included on each side. A retest zone spans the same prices as the zone it takes over.
  • A buy zone is triggered when a bar closes below it (a sell zone, above it); with triggerOnlyTouch, a wick going past it is enough. With triggeredZones, a retest zone (triggered: true) then takes over, until price crosses back through it.
  • A zone and its retest zone live at most extendedBars bars after the bar that created the original zone.
  • Drawing: a zone spans from bar + start × timeframe to bar + end × timeframe (see start and end), and from low to high as published. An original zone ended by the very next bar has an end below its start; this is common: draw it as a stub at bar, or not at all.

When it updates

  • A zone is sent in progress when the bar that creates it closes, sent again on every change, then sent final (active: false, with its end) when it ends.
  • Zones stay active from bar to bar and from session to session. With resetSession: true, zones in progress are ended when the first bar of the new session closes (18:05 New York time with timeframe: 300).
  • <weekSunday> is the YYYY-MM-DD date of the week’s Sunday reopen; <ordinal> numbers the week’s zones in creation order.
  • Weekly reset: on the first trade of the Sunday reopen (18:00 New York time), the week’s last bar is processed, then zones still in progress are sent final (active: false, with their end); none carries over to the new week.

Subscribe

The same params work in real time, on historical data and in exports. Parameters you omit take the defaults of the instrument’s ticker.

Subscribe message
{
  "t": "subscribe",
  "sub": "imbalances",
  "instrument": "NQ.front",
  "indicator": "imbalances",
  "params": {
    "consecutive": 2,
    "extendedBars": 10,
    "extraTicks": 0,
    "groupTicks": 9,
    "includeZero": false,
    "minimumPercent": 300,
    "minimumVolume": 40,
    "mode": "diagonal",
    "resetSession": false,
    "timeframe": 300,
    "triggerOnlyTouch": false,
    "triggeredZones": true
  },
  "mode": "live",
  "from": "live"
}

Parameters

As soon as a parameter differs from its default on the instrument’s ticker, the subscription counts as a custom configuration. To change a parameter, open a new subscription.

The Default column gives the generic default, used by the tickers without a default of their own, then each ticker that has its own value, such as HG 2. Ticker defaults are regularly updated, ticker by ticker: an update changes the results of the subscriptions and queries that rely on them. A subscription whose parameters are all at its instrument’s defaults is not a custom configuration. Only explicit parameters keep a computation identical over time: pass them to keep the same results.

ParameterTypeRoleDefaultAllowed valuesUnitDescription
consecutiveintegerComputation3 · HG 2 · NG 2 · NQ 2 · RTY 2 · YM 2 · ZB 2 · ZN 21 to 20levelsMinimum number of adjacent imbalanced levels to form a zone.
extendedBarsintegerComputation101 to 500barsMaximum lifetime of a zone (and of its retest zone), in bars after the bar that created it.
extraTicksintegerComputation00 to 100ticksPadding added on each side of the zone, above the top and below the bottom.
groupTicksintegerComputation1 · CL 2 · GC 4 · NQ 9 · RTY 2 · YM 21 to 100ticksNumber of ticks grouped into each level before the comparison.
includeZerobooleanComputationfalsetrue · false—Count a level whose opposite side is empty (0 contracts) as an imbalance.
minimumPercentintegerComputation300 · HG 400 · ZB 4001 to 10,000%Imbalance threshold, in percent. With diagonal and horizontal, how many times the dominant side must outweigh the other (300 = 3 to 1). With delta-percentage, the delta’s share of the level’s volume: this mode requires an explicit value of at most 100 (the default is rejected in this mode). Higher = fewer imbalances.
minimumVolumeintegerComputation0 · NG 5 · NQ 40 · RTY 5 · YM 5 · ZB 40 · ZN 400 to 1,000,000contractsMinimum volume difference between the two sides of a level. Higher = fewer imbalances.
modechoiceComputationdiagonaldiagonal · horizontal · delta-percentage—How volumes are compared: diagonal (a level’s ask against the bid of the level just below), horizontal (ask and bid of the same level) or delta-percentage (the level’s delta relative to its volume). Unrelated to the subscription mode (live or confirmed).
resetSessionbooleanComputationfalsetrue · false—End every zone when the first bar of each new session closes.
timeframeintegerComputation3001 · 5 · 10 · 15 · 30 · 60 · 120 · 180 · 300 · 600 · 900 · 1800 · 3600 · 7200 · 10800 · 14400 · 86400secondsBar duration in seconds: from 1 second (1) to 1 day (86400). Bars are counted from the product's session open (18:00 New York time for every current product): 4-hour bars start at 18:00, 22:00, 02:00 and so on, and a 1-day bar covers the whole session.
triggerOnlyTouchbooleanComputationfalsetrue · false—Trigger a zone as soon as a wick goes past it, without waiting for a close beyond it.
triggeredZonesbooleanComputationtruetrue · false—Create a retest zone when a zone is triggered.

Objects received

Each object keeps the same id from one update to the next. Its data is in the data field. Prices are in ticks: Prices and timestamps explains how to convert them.

An object sent in progress arrives with final: false, then again on every change, and each version fully replaces the previous one. Its description says when it ends: most objects end with a last version carrying final: true, and some are removed without one. An object sent final is sent once, with final: true.

Fields and units

Prices are in ticks (Prices and timestamps). Timestamps are nanoseconds since the Unix epoch, sent as strings: parse them as 64-bit integers. The fields below place the objects in time.

FieldUnitHow to read it
zone.bartimestamp (ns) · stringStart of the bar that created the zone (for a retest zone, of the bar that triggered the original zone): the reference of start and end.
zone.startbars · numberOffset from bar, in timeframe-second bars: 0.5 for an original zone, -0.5 for a retest zone.
zone.endbars · numberOffset from bar where the final zone stops, in the same unit. Below start when the next bar ends the zone: draw nothing, or a stub at bar.

zone sent in progress

Zone; in progress while it is active.

id format: <weekSunday>:<ordinal>.

FieldTypeUnitPresentDescription
activeboolean—alwaystrue while the zone is extended; false once it is final.
barstringtimestamp (ns)alwaysStart of the bar that created the zone (for a retest zone, the bar that triggered the original zone).
endnumberbarssometimesEnd of the zone, in the same unit as start (bars relative to bar); present once the zone is final. Matching time: bar + end × timeframe × 10⁹ ns. When the very next bar ends an original zone, end is below start: draw nothing, or a stub at bar.
highintegerticksalwaysTop of the zone, extraTicks padding included: draw the zone from low to high as published, without widening it.
lowintegerticksalwaysBottom of the zone, extraTicks padding included.
sidestring · buy | sell—alwaysBuy or sell imbalance.
startnumberbarsalwaysStart of the zone, in bars relative to bar (0 = start of bar): 0.5 for an original zone, -0.5 for a retest zone. Matching time, in nanoseconds: bar + start × timeframe × 10⁹, rounded to the nanosecond, in 64-bit integers (bar is in nanoseconds; timeframe, in seconds, comes from your parameters).
triggeredboolean—alwaystrue: retest zone, created when a bar triggered a zone; false: original zone.

Example messages

Messages as the WebSocket sends them to the subscription above, taken from a real NQ session. Historical data returns the same objects, with the same cursor, without the sub field.

The params of the subscription above are the current NQ ticker defaults, written out in full.

Object in progress
{
  "sub": "imbalances",
  "cursor": "20720.211987.0",
  "t": "upsert",
  "id": "2026-09-20:45",
  "final": false,
  "ts": "1790262000003551557",
  "data": {
    "side": "sell",
    "high": 122246,
    "low": 122229,
    "triggered": false,
    "active": true,
    "bar": "1790261700000000000",
    "start": 0.5
  }
}
Final object
{
  "sub": "imbalances",
  "cursor": "20720.243902.0",
  "t": "upsert",
  "id": "2026-09-20:47",
  "final": true,
  "ts": "1790264700351357737",
  "data": {
    "side": "sell",
    "high": 122147,
    "low": 122130,
    "triggered": false,
    "active": false,
    "bar": "1790263500000000000",
    "start": 0.5,
    "end": 2
  }
}

JSON schemas

To validate or type your data: the JSON schemas of the parameters and of data, also available from GET /v1/indicators. The SDKs can generate types from them. Rules that compare two parameters, such as a maximum of at least its minimum, and the two decimals of decimal parameters, are only in the parameter descriptions: the API checks them too.

Parameters schema
JSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fathomcharts.com/schemas/imbalances/params.json",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "consecutive": {
      "description": "Minimum number of adjacent imbalanced levels to form a zone.",
      "type": "integer",
      "default": 3,
      "minimum": 1,
      "maximum": 20
    },
    "extendedBars": {
      "description": "Maximum lifetime of a zone (and of its retest zone), in bars after the bar that created it.",
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 500
    },
    "extraTicks": {
      "description": "Padding added on each side of the zone, above the top and below the bottom.",
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 100
    },
    "groupTicks": {
      "description": "Number of ticks grouped into each level before the comparison.",
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "maximum": 100
    },
    "includeZero": {
      "description": "Count a level whose opposite side is empty (0 contracts) as an imbalance.",
      "type": "boolean",
      "default": false
    },
    "minimumPercent": {
      "description": "Imbalance threshold, in percent. With `diagonal` and `horizontal`, how many times the dominant side must outweigh the other (300 = 3 to 1). With `delta-percentage`, the delta’s share of the level’s volume: this mode requires an explicit value of at most 100 (the default is rejected in this mode). Higher = fewer imbalances.",
      "type": "integer",
      "default": 300,
      "minimum": 1,
      "maximum": 10000
    },
    "minimumVolume": {
      "description": "Minimum volume difference between the two sides of a level. Higher = fewer imbalances.",
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 1000000
    },
    "mode": {
      "description": "How volumes are compared: `diagonal` (a level’s ask against the bid of the level just below), `horizontal` (ask and bid of the same level) or `delta-percentage` (the level’s delta relative to its volume). Unrelated to the subscription `mode` (`live` or `confirmed`).",
      "type": "string",
      "default": "diagonal",
      "enum": [
        "diagonal",
        "horizontal",
        "delta-percentage"
      ]
    },
    "resetSession": {
      "description": "End every zone when the first bar of each new session closes.",
      "type": "boolean",
      "default": false
    },
    "timeframe": {
      "description": "Bar duration in seconds: from 1 second (`1`) to 1 day (`86400`). Bars are counted from the product's session open (18:00 New York time for every current product): 4-hour bars start at 18:00, 22:00, 02:00 and so on, and a 1-day bar covers the whole session.",
      "type": "integer",
      "default": 300,
      "enum": [
        1,
        5,
        10,
        15,
        30,
        60,
        120,
        180,
        300,
        600,
        900,
        1800,
        3600,
        7200,
        10800,
        14400,
        86400
      ]
    },
    "triggerOnlyTouch": {
      "description": "Trigger a zone as soon as a wick goes past it, without waiting for a close beyond it.",
      "type": "boolean",
      "default": false
    },
    "triggeredZones": {
      "description": "Create a retest zone when a zone is triggered.",
      "type": "boolean",
      "default": true
    }
  },
  "allOf": [
    {
      "description": "must be given and at most 100 in `delta-percentage` mode (the default is for `diagonal` and `horizontal`)",
      "if": {
        "properties": {
          "mode": {
            "const": "delta-percentage"
          }
        },
        "required": [
          "mode"
        ]
      },
      "then": {
        "properties": {
          "minimumPercent": {
            "maximum": 100
          }
        },
        "required": [
          "minimumPercent"
        ]
      }
    }
  ]
}
data field schema
JSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fathomcharts.com/schemas/imbalances/data.json",
  "title": "zone",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "active": {
      "description": "`true` while the zone is extended; `false` once it is final.",
      "type": "boolean"
    },
    "bar": {
      "description": "Start of the bar that created the zone (for a retest zone, the bar that triggered the original zone).",
      "type": "string",
      "pattern": "^[0-9]+$"
    },
    "end": {
      "description": "End of the zone, in the same unit as `start` (bars relative to `bar`); present once the zone is final. Matching time: `bar` + `end` × `timeframe` × 10⁹ ns. When the very next bar ends an original zone, `end` is below `start`: draw nothing, or a stub at `bar`.",
      "type": "number"
    },
    "high": {
      "description": "Top of the zone, `extraTicks` padding included: draw the zone from `low` to `high` as published, without widening it.",
      "type": "integer"
    },
    "low": {
      "description": "Bottom of the zone, `extraTicks` padding included.",
      "type": "integer"
    },
    "side": {
      "description": "Buy or sell imbalance.",
      "type": "string",
      "enum": [
        "buy",
        "sell"
      ]
    },
    "start": {
      "description": "Start of the zone, in bars relative to `bar` (0 = start of `bar`): `0.5` for an original zone, `-0.5` for a retest zone. Matching time, in nanoseconds: `bar` + `start` × `timeframe` × 10⁹, rounded to the nanosecond, in 64-bit integers (`bar` is in nanoseconds; `timeframe`, in seconds, comes from your parameters).",
      "type": "number"
    },
    "triggered": {
      "description": "`true`: retest zone, created when a bar triggered a zone; `false`: original zone.",
      "type": "boolean"
    }
  },
  "required": [
    "side",
    "high",
    "low",
    "triggered",
    "active",
    "bar",
    "start"
  ]
}