Indicator

Fathom Trades

Likely large aggressive orders, reconstructed from consecutive trades.

What the indicator shows

Each mark is a likely large aggressive order, reconstructed from the burst of small 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 minimum to the instrument: too low, and the real large orders get lost in the noise. maximum limits the reading to a size range.
In live mode, a group appears as soon as it reaches minimum and grows during the burst. In confirmed mode, you only receive final groups.

How it is computed

A burst is a run of consecutive trades on the same aggressor side, at most 5 ms apart (market time), with no price pullback: for a buy group, no trade below the previous one’s price; for a sell group, none above.
A trade whose aggressor is not identified ends the current burst and joins no group.
vwap is the group’s volume-weighted average price. With priceMode: "average", price is that VWAP rounded to the nearest tick, ties to even (124237.5 gives 124238; 124248.5 gives 124248).
minimum, maximum and priceMode are display parameters: they filter groups and choose the published price, without changing the grouping.
The id is <startNs>:<ordinal>: startNs is the group’s start and ordinal numbers the groups that start within the same 100 ns. It is almost always 0; a …:1 can be published without a …:0, when the :0 group stayed below minimum.

When it updates

The group is sent in progress as soon as it reaches minimum, sent again on every trade that extends it, then sent final on the first trade that does not extend it.
A group already sent that exceeds maximum is removed (remove) right away, including in confirmed mode, where its id never arrived: ignore a remove for an unknown id. A group that exceeds maximum before it was sent is never sent.
No reset: each group is independent.

Identifier: big-trades
Objects received: group
Historical cost: 1 compute unit per trade

The same params work in real time, on historical data and in exports. Parameters you omit take their default values.

Subscribe message

{
  "t": "subscribe",
  "sub": "big-trades",
  "instrument": "NQ.front",
  "indicator": "big-trades",
  "params": {
    "minimum": 30,
    "maximum": 0,
    "priceMode": "last"
  },
  "mode": "live",
  "from": "live"
}

Parameters

As soon as a parameter differs from its default, the subscription counts as a custom configuration. A calculation parameter changes the indicator’s result; a display parameter only filters the objects you receive. To change a parameter, open a new subscription.

Parameter	Type	Role	Default	Allowed values	Unit	Description
`minimum`	integer	Display	`30`	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 `minimum`.
`priceMode`	choice	Display	`last`	`last` · `start` · `average`	—	Price published in `price`: last price (`last`), first price (`start`) or the group’s 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: multiply them by the instrument’s tick size (GET /v1/instruments) to get points.

`group` sent in progress

Group of trades; in progress while it keeps growing.

id format: <startNs>:<ordinal>. The object is sent in progress (final: false), then sent again on every change; each version fully replaces the previous one. Once it can no longer change, its last version carries final: true, except for objects whose description says they are removed without a final version.

Field	Type	Unit	Present	Description
`end`	string	timestamp (ns)	always	Timestamp of the last trade. Several trades can carry the same timestamp: `end` then stays the same while `trades` grows.
`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.

Object in progress

{
  "sub": "big-trades",
  "cursor": "20720.501.0",
  "t": "upsert",
  "id": "1790208267461672923:0",
  "final": false,
  "ts": "1790208267461672923",
  "data": {
    "side": "sell",
    "volume": 30,
    "trades": 14,
    "start": "1790208267461672923",
    "end": "1790208267461672923",
    "first": 122991,
    "last": 122979,
    "price": 122979,
    "vwap": 122984.5
  }
}

Final object

{
  "sub": "big-trades",
  "cursor": "20720.509.0",
  "t": "upsert",
  "id": "1790208267461672923:0",
  "final": true,
  "ts": "1790208267468979827",
  "data": {
    "side": "sell",
    "volume": 40,
    "trades": 21,
    "start": "1790208267461672923",
    "end": "1790208267461672923",
    "first": 122991,
    "last": 122976,
    "price": 122976,
    "vwap": 122982.775
  }
}

JSON schemas

To validate or type your data: the JSON schemas of the parameters and of data, also available from GET /v1/indicators. The SDK can generate types from them.

Parameters schema

JSON

{
  "$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 `minimum`.",
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 1000000
    },
    "priceMode": {
      "description": "Price published in `price`: last price (`last`), first price (`start`) or the group’s VWAP rounded to the tick (`average`).",
      "type": "string",
      "default": "last",
      "enum": [
        "last",
        "start",
        "average"
      ]
    }
  }
}

data field schema