# 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` 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 ## Subscribe The same `params` work in [real time](https://fathomcharts.com/docs/websocket.md), on [historical data](https://fathomcharts.com/docs/history.md) and in exports. Parameters you omit take their default values. **Subscribe message** ```json { "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](https://fathomcharts.com/docs/limits.md#how-limits-are-counted). 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: `:`. 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](https://fathomcharts.com/docs/history.md) returns the same objects, with the same `cursor`, without the `sub` field. **Object in progress** ```json { "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** ```json { "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](https://fathomcharts.com/docs/sdk.md#indicator-types). **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** ```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. Several trades can carry the same timestamp: `end` then stays the same while `trades` grows.", "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" ] } ```