Fathom Trades
Likely large aggressive orders, rebuilt from the trades that filled them.
At a glance
- Identifier
big-trades- Objects received
group- Historical cost
- 1 compute unit per trade
What the indicator shows
- Each mark is a likely large aggressive order, rebuilt from the trades that filled it.
- Its side shows who was aggressive: a buy hit the ask, a sell hit the bid.
- On the Fathom chart, its size follows the group’s volume. Its price depends on
priceMode.
How to use it
- Watch for large orders at highs and lows: a large buyer in a dip or a large seller at a top marks a defended level, sometimes a reversal.
- Several large orders on the same side around one price outline a level of interest to watch when price returns.
- Tune
minimumto the instrument: too low, and the real large orders get lost in the noise.maximumlimits the reading to a size range. - In
livemode, a group appears as soon as it reachesminimumand grows while the order fills. Inconfirmedmode, you only receive final groups.
How to read and draw it
- Each group is one likely order:
sideis its aggressor side,volumeandtradesits size,startandendthe times of its first and last trade (market time),firstandlasttheir prices. vwapis the group’s volume-weighted average price. WithpriceMode: "average",priceis that VWAP rounded to the nearest tick, ties to even (124237.5 gives 124238; 124248.5 gives 124248).minimumandmaximumfilter the groups you receive by volume;priceModechooses the published price.- Drawing: place a group at its
price, in the candle that contains itsstart. - The
idis<startNs>:<ordinal>:startNsis the group’sstart, andordinaltells apart the groups that share that value. It is almost always 0; anidending in:1can be published without the one ending in:0, when that group stayed belowminimum.
When it updates
- The group is sent in progress as soon as it reaches
minimum, sent again each time it grows, then sent final once it is complete. The final version’stscan be later thanend: place the group withstartandend, notts. - When a group exceeds
maximum, aremoveis sent for itsidright away. Inlivemode, it removes a group you received; inconfirmedmode, you never received that group: ignore aremovefor an unknownid. A group that exceedsmaximumbefore it was sent is never sent. - No reset: each group 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": "big-trades",
"instrument": "NQ.front",
"indicator": "big-trades",
"params": {
"minimum": 50,
"maximum": 0,
"priceMode": "last"
},
"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. A computation parameter changes the indicator’s result; a display parameter only changes what you receive (which objects, or the published price), not the computation. 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 CL 100. 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 |
|---|---|---|---|---|---|---|
minimum | integer | Display | 30 · CL 100 · ES 125 · NG 40 · NQ 50 · RTY 50 · SI 25 · ZB 500 · ZN 1250 | 1 to 1,000,000 | contracts | Minimum group volume, in contracts. |
maximum | integer | Display | 0 | 0 to 1,000,000 | contracts | Maximum group volume, in contracts; 0 = unlimited, otherwise at least the minimum in effect (the ticker default when minimum is omitted). |
priceMode | choice | Display | last | last · start · average | — | Price published in price: the group’s last price (last), its first price (start) or its VWAP rounded to the tick (average). |
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 |
|---|---|---|
group.id | string · <startNs>:<ordinal> | The group’s start, then an ordinal that tells apart groups starting on the same timestamp. |
group.start | timestamp (ns) · string | Time of the group’s first trade: draw the group in the candle that contains it, at its price. |
group.end | timestamp (ns) · string | Time of the group’s last trade. |
group sent in progress
Likely large order; in progress while it can still grow.
id format: <startNs>:<ordinal>.
| Field | Type | Unit | Present | Description |
|---|---|---|---|---|
end | string | timestamp (ns) | always | Timestamp of the last trade (market time). |
first | integer | ticks | always | Price of the first trade. |
last | integer | ticks | always | Price of the last trade. |
price | integer | ticks | always | Price chosen by priceMode: last price (last), first price (start) or the group’s VWAP rounded to the nearest tick, ties to even (average). |
side | string · buy | sell | — | always | Aggressor side of the group. |
start | string | timestamp (ns) | always | Timestamp of the first trade (market time), also used in the id. |
trades | integer | trades | always | Number of trades in the group. |
volume | integer | contracts | always | Total volume of the group. |
vwap | number | ticks | always | Volume-weighted average price of the group, in ticks, with decimals. |
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": "big-trades",
"cursor": "20720.12410.0",
"t": "upsert",
"id": "1790216112591682253:0",
"final": false,
"ts": "1790216112591682253",
"data": {
"side": "buy",
"volume": 53,
"trades": 11,
"start": "1790216112591682253",
"end": "1790216112591682253",
"first": 122914,
"last": 122924,
"price": 122924,
"vwap": 122919.60377358491
}
}{
"sub": "big-trades",
"cursor": "20720.12431.0",
"t": "upsert",
"id": "1790216112591682253:0",
"final": true,
"ts": "1790216112592942293",
"data": {
"side": "buy",
"volume": 112,
"trades": 31,
"start": "1790216112591682253",
"end": "1790216112592870027",
"first": 122914,
"last": 122939,
"price": 122939,
"vwap": 122925.96428571429
}
}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/big-trades/params.json",
"type": "object",
"additionalProperties": false,
"properties": {
"minimum": {
"description": "Minimum group volume, in contracts.",
"type": "integer",
"default": 30,
"minimum": 1,
"maximum": 1000000
},
"maximum": {
"description": "Maximum group volume, in contracts; 0 = unlimited, otherwise at least the `minimum` in effect (the ticker default when `minimum` is omitted).",
"type": "integer",
"default": 0,
"minimum": 0,
"maximum": 1000000
},
"priceMode": {
"description": "Price published in `price`: the group’s last price (`last`), its first price (`start`) or its VWAP rounded to the tick (`average`).",
"type": "string",
"default": "last",
"enum": [
"last",
"start",
"average"
]
}
}
}data field schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://fathomcharts.com/schemas/big-trades/data.json",
"title": "group",
"type": "object",
"additionalProperties": false,
"properties": {
"end": {
"description": "Timestamp of the last trade (market time).",
"type": "string",
"pattern": "^[0-9]+$"
},
"first": {
"description": "Price of the first trade.",
"type": "integer"
},
"last": {
"description": "Price of the last trade.",
"type": "integer"
},
"price": {
"description": "Price chosen by `priceMode`: last price (`last`), first price (`start`) or the group’s VWAP rounded to the nearest tick, ties to even (`average`).",
"type": "integer"
},
"side": {
"description": "Aggressor side of the group.",
"type": "string",
"enum": [
"buy",
"sell"
]
},
"start": {
"description": "Timestamp of the first trade (market time), also used in the `id`.",
"type": "string",
"pattern": "^[0-9]+$"
},
"trades": {
"description": "Number of trades in the group.",
"type": "integer"
},
"volume": {
"description": "Total volume of the group.",
"type": "integer"
},
"vwap": {
"description": "Volume-weighted average price of the group, in ticks, with decimals.",
"type": "number"
}
},
"required": [
"side",
"volume",
"trades",
"start",
"end",
"first",
"last",
"price",
"vwap"
]
}