Fathom Footprint
Bid and ask volume at each price level, bar by bar.
At a glance
- Identifier
footprint- Objects received
bar- Historical cost
- 1 compute unit per trade
What the indicator shows
- Each bar is split into price levels. At each level, the volume of aggressive selling, filled at the bid, and the volume of aggressive buying, filled at the ask; on the Fathom chart, the bid is on the left and the ask on the right.
- The POC is the level with the most volume traded in the bar; the Fathom chart frames the displayed band containing it.
- On the web chart, Footprint follows the selected candle interval and the instrument’s default tick grouping, with a thin delayed price candle beside each ladder. The illustration uses 16-tick groups on a more volatile recorded session; the engine applies the requested
groupTicksbefore publishing the levels. - When zoomed out, the chart combines neighboring price levels and sums their bid, ask and unidentified volumes to keep rows readable. Zooming in restores the published detail. This display grouping does not change the indicator settings or recalculate the POC.
- A level’s delta (ask minus bid) shows which side was more aggressive at that price. The sum over the levels gives the bar’s delta.
How to use it
- Spot absorption: heavy aggressive volume at an extreme without price moving further shows passive orders soaking up the aggression.
- Follow where the POC sits: at the top of the bar, volume traded at the highs; at the bottom, at the lows.
- Compare bid and ask on neighboring levels to see where one side takes over. The
imbalancesindicator highlights the zones where one side clearly dominates. - Raise
groupTicksfor a more condensed reading on a fast instrument.filterMinandfilterMaxonly count trades of a given size, for example large lots.
How it is computed
- Bars last
timeframeseconds, from 1 second to 1 day, and are counted from the session open (18:00 New York time), like the bars of trading platforms. Bars line up with New York clock times (9:30, 9:35 and so on withtimeframe: 300); withtimeframe: 3600, bars start on the hour, so the 9:30 open falls inside the 9:00 bar. 4-hour bars start at 18:00, 22:00, 02:00, 06:00, 10:00 and 14:00, the last bar of a session ends at its close (17:00), and a 1-day bar (86400) is the whole session. A bar with no counted trade is not sent. - Levels are aligned on multiples of
groupTicksticks: a level’s price is the bottom of its group, so withgroupTicks: 4the first level can be below the bar’slow. levelsvolumes only count trades whose volume is betweenfilterMinandfilterMax, both inclusive. The OHLC (open,high,low,close) is computed on all the bar’s trades, counted or not.- A level’s bid volume comes from aggressive sellers (hitting the bid), its ask volume from aggressive buyers. Level volume =
l[1] + l[2], plus the 4th element when present; delta =l[2] - l[1].
When it updates
- The bar is sent once, final, on the first trade of a later bar; nothing is sent while it is in progress. The last bar before the 17:00 New York break therefore only arrives at the 18:00 reopen, and Friday’s last bar on Sunday evening.
- No reset: each bar is independent.
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": "footprint",
"instrument": "NQ.front",
"indicator": "footprint",
"params": {
"filterMax": 0,
"filterMin": 0,
"groupTicks": 1,
"timeframe": 15
},
"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.
Every ticker currently uses the generic defaults of the Default column. Defaults can be set per ticker and 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 |
|---|---|---|---|---|---|---|
filterMax | integer | Computation | 0 | 0 to 1,000,000 | contracts | Maximum volume for a trade to be counted; 0 = unlimited, otherwise at least filterMin. |
filterMin | integer | Computation | 0 | 0 to 1,000,000 | contracts | Minimum volume for a trade to be counted; 0 = no minimum. |
groupTicks | integer | Computation | 1 | 1 to 100 | ticks | Number of ticks grouped into each price level. |
timeframe | integer | Computation | 15 | 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. |
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 |
|---|---|---|
bar.id | string · <barStartNs> | Start of the bar: it covers timeframe seconds from that time. |
bar sent final
Finished bar that starts at barStartNs, sent on the first trade of a later bar.
id format: <barStartNs>.
| Field | Type | Unit | Present | Description |
|---|---|---|---|---|
close | integer | ticks | always | Close: price of the bar’s last trade, counted or not. |
high | integer | ticks | always | High of the bar, over all its trades. |
levels | array | — | always | Levels by ascending price: [price (ticks), bid volume (contracts), ask volume (contracts)], plus a 4th element when the level holds trades whose aggressor is not identified (their volume, in contracts): [122008, 14, 3, 2] counts 14 contracts at the bid, 3 at the ask and 2 without an identified aggressor. Bid volume comes from aggressive sellers (hitting the bid), ask volume from aggressive buyers. A level’s price is the bottom of its groupTicks-tick group. Level volume = l[1] + l[2], plus the 4th element when present; delta = l[2] - l[1]. |
low | integer | ticks | always | Low of the bar, over all its trades. |
open | integer | ticks | always | Open: price of the bar’s first trade, counted or not. |
poc | integer | ticks | always | Price of the bar’s highest-volume level. On a tie: the lowest of the tied levels at or above the open’s level, otherwise the highest of those below it. |
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": "footprint",
"cursor": "20720.0.0",
"t": "upsert",
"id": "1790207985000000000",
"final": true,
"ts": "1790208000058746563",
"data": {
"open": 123032,
"high": 123032,
"low": 123012,
"close": 123014,
"levels": [
[
123012,
1,
0
],
[
123014,
0,
1
],
[
123015,
1,
0
],
[
123016,
2,
0
],
[
123017,
1,
0
],
[
123018,
1,
0
],
[
123020,
3,
1
],
[
123022,
1,
0
],
[
123024,
1,
0
],
[
123025,
0,
1
],
[
123026,
0,
1
],
[
123027,
0,
2
],
[
123032,
0,
1
]
],
"poc": 123020
}
}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/footprint/params.json",
"type": "object",
"additionalProperties": false,
"properties": {
"filterMax": {
"description": "Maximum volume for a trade to be counted; 0 = unlimited, otherwise at least `filterMin`.",
"type": "integer",
"default": 0,
"minimum": 0,
"maximum": 1000000
},
"filterMin": {
"description": "Minimum volume for a trade to be counted; 0 = no minimum.",
"type": "integer",
"default": 0,
"minimum": 0,
"maximum": 1000000
},
"groupTicks": {
"description": "Number of ticks grouped into each price level.",
"type": "integer",
"default": 1,
"minimum": 1,
"maximum": 100
},
"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": 15,
"enum": [
1,
5,
10,
15,
30,
60,
120,
180,
300,
600,
900,
1800,
3600,
7200,
10800,
14400,
86400
]
}
}
}data field schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://fathomcharts.com/schemas/footprint/data.json",
"title": "bar",
"type": "object",
"additionalProperties": false,
"properties": {
"close": {
"description": "Close: price of the bar’s last trade, counted or not.",
"type": "integer"
},
"high": {
"description": "High of the bar, over all its trades.",
"type": "integer"
},
"levels": {
"description": "Levels by ascending price: `[price (ticks), bid volume (contracts), ask volume (contracts)]`, plus a 4th element when the level holds trades whose aggressor is not identified (their volume, in contracts): `[122008, 14, 3, 2]` counts 14 contracts at the bid, 3 at the ask and 2 without an identified aggressor. Bid volume comes from aggressive sellers (hitting the bid), ask volume from aggressive buyers. A level’s price is the bottom of its `groupTicks`-tick group. Level volume = `l[1] + l[2]`, plus the 4th element when present; delta = `l[2] - l[1]`.",
"type": "array",
"items": {
"type": "array",
"maxItems": 4,
"minItems": 3,
"prefixItems": [
{
"type": "integer"
},
{
"type": "integer",
"minimum": 0
},
{
"type": "integer",
"minimum": 0
},
{
"type": "integer",
"minimum": 0
}
]
}
},
"low": {
"description": "Low of the bar, over all its trades.",
"type": "integer"
},
"open": {
"description": "Open: price of the bar’s first trade, counted or not.",
"type": "integer"
},
"poc": {
"description": "Price of the bar’s highest-volume level. On a tie: the lowest of the tied levels at or above the open’s level, otherwise the highest of those below it.",
"type": "integer"
}
},
"required": [
"open",
"high",
"low",
"close",
"levels",
"poc"
]
}