Indicator

Fathom Footprint

Bid and ask volume at each price level, bar by bar.

At a glance

Identifier
footprint
Objects received
bar
Historical cost
1 compute unit per trade

What the indicator shows

  • Each bar is split into price levels. At each level, the volume of aggressive selling, filled at the bid, and the volume of aggressive buying, filled at the ask; on the Fathom chart, the bid is on the left and the ask on the right.
  • The POC is the level with the most volume traded in the bar; the Fathom chart frames the displayed band containing it.
  • On the web chart, Footprint follows the selected candle interval and the instrument’s default tick grouping, with a thin delayed price candle beside each ladder. The illustration uses 16-tick groups on a more volatile recorded session; the engine applies the requested groupTicks before publishing the levels.
  • When zoomed out, the chart combines neighboring price levels and sums their bid, ask and unidentified volumes to keep rows readable. Zooming in restores the published detail. This display grouping does not change the indicator settings or recalculate the POC.
  • A level’s delta (ask minus bid) shows which side was more aggressive at that price. The sum over the levels gives the bar’s delta.

How to use it

  • Spot absorption: heavy aggressive volume at an extreme without price moving further shows passive orders soaking up the aggression.
  • Follow where the POC sits: at the top of the bar, volume traded at the highs; at the bottom, at the lows.
  • Compare bid and ask on neighboring levels to see where one side takes over. The imbalances indicator highlights the zones where one side clearly dominates.
  • Raise groupTicks for a more condensed reading on a fast instrument. filterMin and filterMax only count trades of a given size, for example large lots.

How it is computed

  • Bars last timeframe seconds, from 1 second to 1 day, and are counted from the session open (18:00 New York time), like the bars of trading platforms. Bars line up with New York clock times (9:30, 9:35 and so on with timeframe: 300); with timeframe: 3600, bars start on the hour, so the 9:30 open falls inside the 9:00 bar. 4-hour bars start at 18:00, 22:00, 02:00, 06:00, 10:00 and 14:00, the last bar of a session ends at its close (17:00), and a 1-day bar (86400) is the whole session. A bar with no counted trade is not sent.
  • Levels are aligned on multiples of groupTicks ticks: a level’s price is the bottom of its group, so with groupTicks: 4 the first level can be below the bar’s low.
  • levels volumes only count trades whose volume is between filterMin and filterMax, both inclusive. The OHLC (open, high, low, close) is computed on all the bar’s trades, counted or not.
  • A level’s bid volume comes from aggressive sellers (hitting the bid), its ask volume from aggressive buyers. Level volume = l[1] + l[2], plus the 4th element when present; delta = l[2] - l[1].

When it updates

  • The bar is sent once, final, on the first trade of a later bar; nothing is sent while it is in progress. The last bar before the 17:00 New York break therefore only arrives at the 18:00 reopen, and Friday’s last bar on Sunday evening.
  • No reset: each bar 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": "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 on the instrument’s ticker, the subscription counts as a custom configuration. To change a parameter, open a new subscription.

Every ticker currently uses the generic defaults of the Default column. Defaults can be set per ticker and 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
filterMaxintegerComputation00 to 1,000,000contractsMaximum volume for a trade to be counted; 0 = unlimited, otherwise at least filterMin.
filterMinintegerComputation00 to 1,000,000contractsMinimum volume for a trade to be counted; 0 = no minimum.
groupTicksintegerComputation11 to 100ticksNumber of ticks grouped into each price level.
timeframeintegerComputation151 · 5 · 10 · 15 · 30 · 60 · 120 · 180 · 300 · 600 · 900 · 1800 · 3600 · 7200 · 10800 · 14400 · 86400secondsBar duration in seconds: from 1 second (1) to 1 day (86400). Bars are counted from the product's session open (18:00 New York time for every current product): 4-hour bars start at 18:00, 22:00, 02:00 and so on, and a 1-day bar covers the whole session.

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
bar.idstring · <barStartNs>Start of the bar: it covers timeframe seconds from that time.

bar sent final

Finished bar that starts at barStartNs, sent on the first trade of a later bar.

id format: <barStartNs>.

FieldTypeUnitPresentDescription
closeintegerticksalwaysClose: price of the bar’s last trade, counted or not.
highintegerticksalwaysHigh of the bar, over all its trades.
levelsarray—alwaysLevels by ascending price: [price (ticks), bid volume (contracts), ask volume (contracts)], plus a 4th element when the level holds trades whose aggressor is not identified (their volume, in contracts): [122008, 14, 3, 2] counts 14 contracts at the bid, 3 at the ask and 2 without an identified aggressor. Bid volume comes from aggressive sellers (hitting the bid), ask volume from aggressive buyers. A level’s price is the bottom of its groupTicks-tick group. Level volume = l[1] + l[2], plus the 4th element when present; delta = l[2] - l[1].
lowintegerticksalwaysLow of the bar, over all its trades.
openintegerticksalwaysOpen: price of the bar’s first trade, counted or not.
pocintegerticksalwaysPrice of the bar’s highest-volume level. On a tie: the lowest of the tied levels at or above the open’s level, otherwise the highest of those below it.

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.

Final object
{
  "sub": "footprint",
  "cursor": "20720.0.0",
  "t": "upsert",
  "id": "1790207985000000000",
  "final": true,
  "ts": "1790208000058746563",
  "data": {
    "open": 123032,
    "high": 123032,
    "low": 123012,
    "close": 123014,
    "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
  }
}

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/footprint/params.json",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "filterMax": {
      "description": "Maximum volume for a trade to be counted; 0 = unlimited, otherwise at least `filterMin`.",
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 1000000
    },
    "filterMin": {
      "description": "Minimum volume for a trade to be counted; 0 = no minimum.",
      "type": "integer",
      "default": 0,
      "minimum": 0,
      "maximum": 1000000
    },
    "groupTicks": {
      "description": "Number of ticks grouped into each price level.",
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "maximum": 100
    },
    "timeframe": {
      "description": "Bar duration in seconds: from 1 second (`1`) to 1 day (`86400`). Bars are counted from the product's session open (18:00 New York time for every current product): 4-hour bars start at 18:00, 22:00, 02:00 and so on, and a 1-day bar covers the whole session.",
      "type": "integer",
      "default": 15,
      "enum": [
        1,
        5,
        10,
        15,
        30,
        60,
        120,
        180,
        300,
        600,
        900,
        1800,
        3600,
        7200,
        10800,
        14400,
        86400
      ]
    }
  }
}
data field schema
JSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fathomcharts.com/schemas/footprint/data.json",
  "title": "bar",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "close": {
      "description": "Close: price of the bar’s last trade, counted or not.",
      "type": "integer"
    },
    "high": {
      "description": "High of the bar, over all its trades.",
      "type": "integer"
    },
    "levels": {
      "description": "Levels by ascending price: `[price (ticks), bid volume (contracts), ask volume (contracts)]`, plus a 4th element when the level holds trades whose aggressor is not identified (their volume, in contracts): `[122008, 14, 3, 2]` counts 14 contracts at the bid, 3 at the ask and 2 without an identified aggressor. Bid volume comes from aggressive sellers (hitting the bid), ask volume from aggressive buyers. A level’s price is the bottom of its `groupTicks`-tick group. Level volume = `l[1] + l[2]`, plus the 4th element when present; delta = `l[2] - l[1]`.",
      "type": "array",
      "items": {
        "type": "array",
        "maxItems": 4,
        "minItems": 3,
        "prefixItems": [
          {
            "type": "integer"
          },
          {
            "type": "integer",
            "minimum": 0
          },
          {
            "type": "integer",
            "minimum": 0
          },
          {
            "type": "integer",
            "minimum": 0
          }
        ]
      }
    },
    "low": {
      "description": "Low of the bar, over all its trades.",
      "type": "integer"
    },
    "open": {
      "description": "Open: price of the bar’s first trade, counted or not.",
      "type": "integer"
    },
    "poc": {
      "description": "Price of the bar’s highest-volume level. On a tie: the lowest of the tied levels at or above the open’s level, otherwise the highest of those below it.",
      "type": "integer"
    }
  },
  "required": [
    "open",
    "high",
    "low",
    "close",
    "levels",
    "poc"
  ]
}