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.
modechooses how the two sides are compared, andminimumPercenthow strongly one side must dominate. - When at least
consecutiveadjacent 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
consecutiveto keep only the clearest imbalances.
How to read and draw it
modechooses how the buying and selling volume of the bar’s price levels are compared (see the parameter);groupTickssets the size of those levels. RaisingminimumPercent,minimumVolumeorconsecutivekeeps only the clearest imbalances: fewer zones.includeZeroalso counts the levels where one side traded nothing.- With
delta-percentage,minimumPercentmust be given, at most 100: the default is rejected in this mode. - A zone spans from
low, its bottom, tohigh, its top,extraTicksticks 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. WithtriggeredZones, a retest zone (triggered: true) then takes over, until price crosses back through it. - A zone and its retest zone live at most
extendedBarsbars after the bar that created the original zone. - Drawing: a zone spans from
bar + start × timeframetobar + end × timeframe(seestartandend), and fromlowtohighas published. An original zone ended by the very next bar has anendbelow itsstart; this is common: draw it as a stub atbar, 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 itsend) 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 withtimeframe: 300). <weekSunday>is theYYYY-MM-DDdate 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 theirend); 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.
{
"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.
| Parameter | Type | Role | Default | Allowed values | Unit | Description |
|---|---|---|---|---|---|---|
consecutive | integer | Computation | 3 · HG 2 · NG 2 · NQ 2 · RTY 2 · YM 2 · ZB 2 · ZN 2 | 1 to 20 | levels | Minimum number of adjacent imbalanced levels to form a zone. |
extendedBars | integer | Computation | 10 | 1 to 500 | bars | Maximum lifetime of a zone (and of its retest zone), in bars after the bar that created it. |
extraTicks | integer | Computation | 0 | 0 to 100 | ticks | Padding added on each side of the zone, above the top and below the bottom. |
groupTicks | integer | Computation | 1 · CL 2 · GC 4 · NQ 9 · RTY 2 · YM 2 | 1 to 100 | ticks | Number of ticks grouped into each level before the comparison. |
includeZero | boolean | Computation | false | true · false | — | Count a level whose opposite side is empty (0 contracts) as an imbalance. |
minimumPercent | integer | Computation | 300 · HG 400 · ZB 400 | 1 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. |
minimumVolume | integer | Computation | 0 · NG 5 · NQ 40 · RTY 5 · YM 5 · ZB 40 · ZN 40 | 0 to 1,000,000 | contracts | Minimum volume difference between the two sides of a level. Higher = fewer imbalances. |
mode | choice | Computation | diagonal | diagonal · 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). |
resetSession | boolean | Computation | false | true · false | — | End every zone when the first bar of each new session closes. |
timeframe | integer | Computation | 300 | 1 · 5 · 10 · 15 · 30 · 60 · 120 · 180 · 300 · 600 · 900 · 1800 · 3600 · 7200 · 10800 · 14400 · 86400 | seconds | 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. |
triggerOnlyTouch | boolean | Computation | false | true · false | — | Trigger a zone as soon as a wick goes past it, without waiting for a close beyond it. |
triggeredZones | boolean | Computation | true | true · 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.
| Field | Unit | How to read it |
|---|---|---|
zone.bar | timestamp (ns) · string | Start 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.start | bars · number | Offset from bar, in timeframe-second bars: 0.5 for an original zone, -0.5 for a retest zone. |
zone.end | bars · number | Offset 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>.
| Field | Type | Unit | Present | Description |
|---|---|---|---|---|
active | boolean | — | always | true while the zone is extended; false once it is final. |
bar | string | timestamp (ns) | always | Start of the bar that created the zone (for a retest zone, the bar that triggered the original zone). |
end | number | bars | sometimes | 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. |
high | integer | ticks | always | Top of the zone, extraTicks padding included: draw the zone from low to high as published, without widening it. |
low | integer | ticks | always | Bottom of the zone, extraTicks padding included. |
side | string · buy | sell | — | always | Buy or sell imbalance. |
start | number | bars | always | 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). |
triggered | boolean | — | always | true: 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.
{
"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
}
}{
"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
{
"$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
{
"$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"
]
}