Indicator

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 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 while the order fills. In confirmed mode, you only receive final groups.

How to read and draw it

  • Each group is one likely order: side is its aggressor side, volume and trades its size, start and end the times of its first and last trade (market time), first and last their prices.
  • 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 and maximum filter the groups you receive by volume; priceMode chooses the published price.
  • Drawing: place a group at its price, in the candle that contains its start.
  • The id is <startNs>:<ordinal>: startNs is the group’s start, and ordinal tells apart the groups that share that value. It is almost always 0; an id ending in :1 can be published without the one ending in :0, when that group stayed below minimum.

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’s ts can be later than end: place the group with start and end, not ts.
  • When a group exceeds maximum, a remove is sent for its id right away. In live mode, it removes a group you received; in confirmed mode, you never received that group: 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.

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": "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.

ParameterTypeRoleDefaultAllowed valuesUnitDescription
minimumintegerDisplay30 · CL 100 · ES 125 · NG 40 · NQ 50 · RTY 50 · SI 25 · ZB 500 · ZN 12501 to 1,000,000contractsMinimum group volume, in contracts.
maximumintegerDisplay00 to 1,000,000contractsMaximum group volume, in contracts; 0 = unlimited, otherwise at least the minimum in effect (the ticker default when minimum is omitted).
priceModechoiceDisplaylastlast · 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.

FieldUnitHow to read it
group.idstring · <startNs>:<ordinal>The group’s start, then an ordinal that tells apart groups starting on the same timestamp.
group.starttimestamp (ns) · stringTime of the group’s first trade: draw the group in the candle that contains it, at its price.
group.endtimestamp (ns) · stringTime of the group’s last trade.

group sent in progress

Likely large order; in progress while it can still grow.

id format: <startNs>:<ordinal>.

FieldTypeUnitPresentDescription
endstringtimestamp (ns)alwaysTimestamp of the last trade (market time).
firstintegerticksalwaysPrice of the first trade.
lastintegerticksalwaysPrice of the last trade.
priceintegerticksalwaysPrice chosen by priceMode: last price (last), first price (start) or the group’s VWAP rounded to the nearest tick, ties to even (average).
sidestring · buy | sell—alwaysAggressor side of the group.
startstringtimestamp (ns)alwaysTimestamp of the first trade (market time), also used in the id.
tradesintegertradesalwaysNumber of trades in the group.
volumeintegercontractsalwaysTotal volume of the group.
vwapnumberticksalwaysVolume-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.

Object in progress
{
  "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
  }
}
Final object
{
  "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
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 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
JSON
{
  "$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"
  ]
}