Indicator

Fathom Footprint

Look inside the candle. The raw detail, price by price: volume traded at the bid and the ask, to read the pressure on both sides.

15-, 60- or 300-second bars. Each price level (grouped by groupTicks) carries the volume of aggressive sells (bid) and aggressive buys (ask). The size filter only counts trades whose volume falls within its bounds. The current bar is republished on every counted trade (provisional, full state), then published as final when the next bar opens.

Identifier: footprint
Objects received: bar
Calculation: Recent trades
Historical cost: 4 units per trade

The same params work in real time, on historical data and in exports. Any you leave out take their default value.

Subscribe message

{
  "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, the subscription counts as a custom configuration. A new value may require preparing a new calculation (status warming).

Parameter	Type	Default	Allowed values	Unit	Description
`filterMax`	integer	`0`	0 to 1,000,000	contracts	Maximum volume for a trade to be counted; 0 = unlimited, otherwise at least `filterMin`.
`filterMin`	integer	`0`	0 to 1,000,000	contracts	Minimum volume for a trade to be counted; 0 = no minimum.
`groupTicks`	integer	`1`	1 to 100	ticks	Number of ticks grouped into each price level.
`timeframe`	integer	`15`	15 · 60 · 300	—	Bar duration in seconds: 15, 60 or 300.

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.

`bar` updated continuously

Bar; provisional while it is still open.

Format of the id: <barStartNs>. While it changes, the object is sent with final: false, and each new version fully replaces the previous one. Its last version carries final: true.

Field	Type	Unit	Present	Description
`levels`	array	ticks	always	Levels by ascending price: `[price, bid, ask]`, plus a 4th element when the level holds trades with no aggressor side (their volume). Volume = sum of elements 2 to 4; delta = ask − bid.
`poc`	integer	ticks	always	Price of the highest-volume level; on a tie, the first one found moving away from the open, upward first, then downward.

Calculation warm-up

This indicator only depends on recent trades. If nobody is using your parameters yet, you briefly receive a status warming before the snapshot.

Historical data follows the same rules: a query over a past period returns exactly what the real-time stream published.

Example messages

Messages received with the subscription parameters above. Over WebSocket, each message also carries sub and cursor.

Final version

{
  "t": "upsert",
  "id": "1790207985000000000",
  "final": true,
  "ts": "1790208000058746563",
  "data": {
    "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
  }
}

In-progress version

{
  "t": "upsert",
  "id": "1790208000000000000",
  "final": false,
  "ts": "1790208000058746563",
  "data": {
    "levels": [
      [
        123014,
        1,
        0
      ]
    ],
    "poc": 123014
  }
}

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/footprint/params.json",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "filterMax": {
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 1000000,
      "description": "Maximum volume for a trade to be counted; 0 = unlimited, otherwise at least `filterMin`."
    },
    "filterMin": {
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 1000000,
      "description": "Minimum volume for a trade to be counted; 0 = no minimum."
    },
    "groupTicks": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "maximum": 100,
      "description": "Number of ticks grouped into each price level."
    },
    "timeframe": {
      "type": "integer",
      "default": 15,
      "enum": [
        15,
        60,
        300
      ],
      "description": "Bar duration in seconds: 15, 60 or 300."
    }
  }
}

Schema of the data field