Developers

Bring Fathom into your tools

Fathom Charts computes your order flow indicators server-side and sends you the results, ready to display. In real time over WebSocket, or over any past period through the REST API, with exactly the same parameters.

New to the vocabulary? The glossary defines every term these pages use: cursor, snapshot, tick, front month, the several meanings of “live”…

How it works

You pick three things:

  • an instrument: what you send in the instrument field. It is either a specific futures contract, such as NQZ6 (E-mini Nasdaq-100, December 2026) or ESZ6 (E-mini S&P 500, December 2026), or an alias, NQ.front or ES.front, that automatically follows the most traded contract of its ticker (the front month);
  • an indicator from the catalog: big-trades, footprint, liquidity-walls…;
  • its parameters: parameters you omit take their default values, which are set per ticker and updated over time. To keep exactly the same computation over time, pass the parameters explicitly.

The ticker, or product, is the root of a contract symbol: NQ for NQZ6 and NQH7, ES for ESZ6. Every contract of a ticker, and its alias, share the same default values.

The server runs the indicator on the market’s trades and sends you objects: a large order (Fathom Trades, big-trades), a footprint bar, a zone… Display them or store them as they are.

Access

Every request and every connection is authenticated with an API key, created from your account (see Authentication). A key (fc_live_…) has the rights of your plans: real time and the last 7 days of history with the Live plan, the full history with the Historical plan. Without a plan, it has the free Sandbox rights: the stream delayed by 10 minutes and the last 7 days of history. Scopes limit what each key may do.

Keep your keys on your server. A web page opens the stream with a short-lived stream token that your server requests, never with a key.

Objects

On the WebSocket, you open a subscription with a subscribe message. The server accepts it with a subscribed message, then sends a snapshot: the current state of the objects. Every change follows, as it happens. Over history, you receive the same changes for a past range.

Every object has a stable id. The server sends two kinds of updates:

  • upsert: creates the object, or replaces it entirely if it already exists;
  • remove: deletes the object.

An object still being built (a big-trades group still growing, for example) arrives with final: false and can still change. Once complete, it is sent one last time with final: true: its data will not change again, but it can still be deleted by a remove (for example a key-levels level that leaves the window). By default (live mode, which has nothing to do with the Live plan), you also receive every intermediate version. If you only need completed results, use confirmed mode, in real time as well as over history.

Sometimes the objects you hold can no longer be updated: the alias moved to a new contract, your access changed, or we updated the computation. The server then sends a reset: discard the objects of that subscription, a new snapshot follows (see Reset).

Every message has a t field that gives its type (subscribed, snapshot, upsert, remove, status, hb…), and every message about one subscription carries the name you gave it, sub. History items carry the same t: upsert or remove.

Prices and timestamps

Prices are expressed in ticks. To get a price in points, multiply the ticks by the instrument’s tick size: ticks × tickSizeNanos × 10⁻⁹. tickSizeNanos is the tick size in billionths of a point, given by GET /v1/instruments (see Instruments) and in every subscribed message. For NQ and ES, it is "250000000", that is 0.25 points, so 122,017 ticks × 0.25 = 30,504.25 points.

A trade price is always a whole number of ticks, but a computed price can fall between two ticks. This is the case for a VWAP, for the middle of a range such as the MP level of key-levels, which is (high + low) / 2, and for the bounds of an effort-zones zone, which can fall on a half tick. Treat prices as numbers, not integers, and do not round them.

Timestamps (ts, start, end, bar and the <…Ns> parts of ids) are nanoseconds since January 1, 1970 UTC, sent as strings. They exceed the precision of a JavaScript number (2⁵³): Number("1790256600533489285") displays 1790256600533489400, so the last digits are lost. Parse them with BigInt; for a chart in seconds: Number(BigInt(ts) / 1_000_000_000n). Some fields count bars rather than time: a bar index in effort-zones (zone.start and zone.end, while bar.start is a timestamp), an offset from the start of the bar bar in flow-tracker, imbalances and opening-range. Each indicator page gives the unit of every field.

Instruments

GET /v1/instruments lists the instruments served and their tick size. It requires an API key, whatever its scope. NQ (E-mini Nasdaq-100: NQZ6, NQ.front) and ES (E-mini S&P 500: ESZ6, ES.front) are served the same way, both with a tick size of 0.25 points.

BASH
curl https://api.fathomcharts.com/v1/instruments -H "Authorization: Bearer $FATHOM_CHARTS_API_KEY"
JSON
{
  "instruments": [
    {
      "symbol": "ESZ6",
      "alias": "ES.front",
      "tickSizeNanos": "250000000",
      "status": "live",
      "updatedAt": "1790256600000000000"
    },
    {
      "symbol": "NQZ6",
      "alias": "NQ.front",
      "tickSizeNanos": "250000000",
      "status": "live",
      "updatedAt": "1790256600000000000"
    }
  ]
}
FieldContent
symbolThe contract symbol, to pass as instrument.
aliasThe alias that designates this contract today (NQ.front), or null.
tickSizeNanosThe tick size in billionths of a point (units of 10⁻⁹), as a string: "250000000" = 0.25.
statusThe state of the instrument’s data: live, warming, source_delayed, source_down or market_closed (see Stream status).
updatedAtWhen this information last changed: a timestamp in nanoseconds, as a string.

Symbols and aliases are case-sensitive, everywhere: nqz6 is rejected with 404 UNKNOWN_INSTRUMENT. The list only holds the contracts followed in real time. An expired contract of a served ticker (NQU6, for example) is no longer in it, but can still be queried over history and exports. Symbols come back every 10 years: in real time, NQZ6 is the December 2026 contract. Over history and exports, a symbol designates the contract listed under it at from, so NQZ6 with a from in 2016 reads the December 2016 contract. When no contract was listed under that symbol in the 7 UTC days before from, the query is rejected with 404 UNKNOWN_INSTRUMENT (see Available range).

GET /v1/status, with an API key, also gives the state of the computation (engine.state: up or down), the state of each instrument without the tick size, and the announced maintenance windows:

JSON
{
  "engine": { "state": "up" },
  "instruments": [
    { "symbol": "NQZ6", "alias": "NQ.front", "status": "live", "updatedAt": "1790256600000000000" }
  ],
  "maintenance": [
    { "id": "6f1c2a7e-0b5d-4c1e-9a3f-2d8e4b7c1a90", "startsAt": "1791295200000000000", "endsAt": "1791295500000000000", "message": "Computation update: each subscription restarts from a new snapshot." }
  ]
}

maintenance lists the windows announced and not over yet, by start time. It is an empty array when none is announced.

Sessions, weeks and front month

The market trades from Sunday evening to Friday afternoon, New York time, with a one-hour break every day. The API uses two clocks: New York time for the sessions, UTC for everything else.

WhatClockBoundaries
SessionNew York timeFrom 18:00 to 17:00 the next day, named by its closing date: session 2026-09-24 starts on September 23 at 18:00. The market pauses every day from 17:00 to 18:00, and over the weekend from Friday 17:00 to Sunday 18:00.
Trading weekUTCStarts on Saturday at 00:00 UTC, the origin of the computation and of the replay over history (origin: week in the catalog). Its first trade comes at the Sunday reopen, at 18:00 New York time.
BarsSession openA bar of timeframe seconds starts on a multiple of timeframe counted from the session open, like the bars of trading platforms; a 1-day bar is the whole session. Every current session opens at 18:00 New York time, a whole number of hours from UTC, so bars of one hour or less also start on multiples of timeframe from 00:00 UTC.
Timestamps, cursors, history daysUTCTimestamps count from January 1, 1970 UTC. The day of a cursor and the days that history serves are UTC days.

A bar is published when it closes, on the first trade after its end. The last bar before the 17:00 break (New York time) therefore arrives at the 18:00 reopen, and Friday’s last bar at the Sunday reopen.

Daylight saving time

New York changes its clocks, UTC never does. On Sunday, November 1, 2026, New York goes from summer time (UTC−4) to winter time (UTC−5):

Friday, October 30 (summer time)Monday, November 2 (winter time)
Session opens (18:00 New York time, the evening before)Thursday 22:00 UTCSunday 23:00 UTC
US cash open (09:30 New York time)13:30 UTC14:30 UTC
Daily break (17:00 to 18:00 New York time)21:00 to 22:00 UTC22:00 to 23:00 UTC
Midnight UTC, when a new day of history becomes available20:00 New York time19:00 New York time
  • The clock change happens during the weekend closure. The trading week that reopens on Sunday, November 1 starts on Saturday, October 31 at 00:00 UTC, like any other, and its weekly ids carry the date 2026-11-01.
  • Session 2026-11-02 runs from Sunday 18:00 (23:00 UTC) to Monday 17:00 (22:00 UTC) New York time.
  • The one-hour bar (timeframe: 3600) that holds the cash open starts at 13:00 UTC on October 30 and at 14:00 UTC on November 2: at 09:00 New York time on both days.
  • Longer bars are counted from the session open, like the bars of trading platforms. The 4-hour bars (timeframe: 14400) of session 2026-11-02 start at 23:00, 03:00, 07:00, 11:00, 15:00 and 19:00 UTC (18:00, 22:00, 02:00, 06:00, 10:00 and 14:00 New York time); the last one ends at the 17:00 close. The 1-day bar (timeframe: 86400) is the whole session, from 23:00 UTC.
  • What follows New York time (the session boundaries, the regular open where opening-range starts) does so in summer and in winter. To label a chart in New York time, convert each timestamp with the America/New_York time zone, not with a fixed offset.

Weekly and session indicators

  • Weeks: the weekly indicators (effort-zones, liquidity-walls, flow-tracker, imbalances, vwap-bands) start over with every trading week: nothing carries over from one week to the next. Within the week, vwap-bands in its default daily mode also starts over with every session, and imbalances with resetSession: true ends its zones at each session. An object still in progress at the Friday close is completed by the first trade of the Sunday reopen: a zone, rectangle or line still extended then ends as at a session open (active: false, with its end). Their dated ids carry the date of the Sunday the week opens, not of the Saturday (bar:2026-09-20:2939 for the week that resumes on Sunday, September 20), like key-levels (week:2026-09-20).
  • Session by session: session-profile and opening-range start over with every session. The ids of opening-range carry the session date (range:2026-10-05), those of session-profile the start of their bar. Their computation, and so the replay over history, still starts from the start of the trading week.
  • Opening: opening-range measures the range from the product’s regular open, New York time, summer and winter alike: 09:30 for NQ, ES, RTY and YM, 09:00 for CL and NG, 08:20 for GC, ZB and ZN, 08:25 for SI and 08:10 for HG.

Front month

NQ.front designates the most traded NQ contract, ranked by volume (not by nearest expiry), and ES.front the most traded ES contract. This choice is re-evaluated every day at midnight UTC, so in the middle of a session: NQ.front moved from NQU6 to NQZ6 on September 16, 2026 at 00:00 UTC. When it changes, every subscription on the alias receives a reset with reason roll, then carries on with the new contract (see Reset).

Over history, a query on an alias reads, for its whole range, the contract the alias designated at from; the response names it in instrument. A range that crosses a rollover therefore stays on the old contract: make one query per contract (NQZ6, then NQH7). A WebSocket subscription that starts in the past on an alias reads the contract the alias designates now, named in subscribed.

Cursors

Every snapshot and every update carries a cursor: its position in the stream. Keep the last one you received. After a disconnect, it lets you resume exactly where you left off, with nothing missed. A message you already processed may be sent again: ignore any upsert or remove whose cursor is less than or equal to the last one you processed (the SDK does this for you). See Cursors and resuming, and their format.

Real time and history, same results

The same computation runs live and over history. With the same parameters, a historical query returns exactly the objects, values and cursors the real-time stream published. Backtest a strategy on the past, then plug it into the live market with no discrepancy.

Two kinds of updates change results over time. Both come with a new engine in subscribed and a reset with reason engine_change (see Updates and maintenance):

  • an update of the default values changes the results of every subscription and query that omits those parameters, over past ranges too. Passing your parameters explicitly protects you from it;
  • an update of how an indicator is computed is announced in advance with a maintenance notice.

The data comes from the market’s trades. If the source is interrupted, the stream tells you: no data is ever made up or filled in.

Default values

A parameter has two levels of default values, both listed on each indicator page and in the catalog (GET /v1/indicators):

  • the ticker default, set for one ticker (productDefaults in the catalog, for example productDefaults.NQ). It applies to every contract of that ticker and to its alias;
  • the generic default (the default of the parameter in the catalog), for a ticker that has no default of its own for that parameter.

A parameter you omit takes the ticker default when there is one, otherwise the generic default. Ticker defaults are regularly updated, ticker by ticker. An update changes the results of every subscription and query that relies on them, from then on: a historical query uses the defaults in force when you run it, not those in force at the time of the data, so the same past range can give different results before and after an update.

Only explicit parameters keep a computation identical over time. To compare a backtest with live trading, or to store results you will query again later, pass every parameter with its value. A subscription whose parameters differ from the current defaults of its ticker uses a custom configuration.

Displaying on a chart

  • Prices: convert ticks to points as explained in Prices and timestamps. Do not round computed prices (VWAP, MP level…).
  • Time: convert timestamps with BigInt (see Prices and timestamps). Bars start on multiples of timeframe from the session open (from 00:00 UTC too, up to one hour); sessions follow New York time (see Daylight saving time).
  • Bar objects (footprint, vwap-bands, session-profile): their id is the bar start, but their values are those at the bar’s close. Place them at the bar start, like a candle, keeping in mind that a VWAP point is valid at the end of the bar.
  • Range of a query: from and to bound updates by reception time, not objects. A one-minute footprint query from 13:30 to 13:55 UTC returns the 13:29 bar (published by the first trade at 13:30), but not the 13:54 bar (published after to). To get every bar of a range, extend to by one bar. The last bar of a session is published by the first trade of the 18:00 New York reopen: a range that ends at the 17:00 close does not contain it.
  • Large orders: place a big-trades group at its price, in the candle that contains its start.

Glossary

  • API key: the secret that authenticates your server, sent in the Authorization: Bearer header. Every key (fc_live_…) has the rights of your plans, the Sandbox rights without a plan.
  • stream token: a single-use token, valid for 60 seconds, that your server requests with its key so that a web page can open the stream.
  • instrument: what you send in instrument: a contract (NQZ6) or an alias (NQ.front).
  • contract: a futures contract with its expiry, such as NQZ6, the December 2026 E-mini Nasdaq-100 contract.
  • ticker or product: the root of a contract symbol, such as NQ or ES. Default values are set per ticker.
  • alias: a name that follows the front month from one contract to the next: NQ.front, ES.front.
  • front month: the most traded contract of a ticker, ranked by volume, not by nearest expiry (NQ.front, ES.front).
  • subscription: following an instrument, an indicator and its parameters on a WebSocket connection (subscribe message).
  • subscribed: the message that accepts a subscription. It names the contract served and the engine.
  • snapshot: the starting state of a subscription, or of a historical query with snapshot: true.
  • upsert: an update that creates an object, or replaces it entirely if it already exists.
  • remove: an update that deletes an object.
  • final: true on the last version of an object. Its data no longer changes.
  • mode: live sends every version of an object, confirmed only its final version.
  • live: the word has several meanings. The live mode sends every version of an object (as opposed to confirmed). The Live plan gives real-time data. Every API key starts with fc_live_, whatever your plan. The live status means the stream is following the market normally. from: "live" starts a subscription now, without going back in time.
  • reset: a message that tells you to discard the state of a subscription. A new snapshot follows.
  • status: a message that gives the state of a subscription’s data: live, warming, source_delayed, source_down or market_closed (see Stream status).
  • lagMs: the internal processing delay of our computation, in milliseconds, sent with each status. It is not a market data latency.
  • hb (heartbeat): a message the server sends every 5 seconds on every connection. If you receive nothing for 15 seconds, treat the connection as lost.
  • cursor: the position of an update in the stream; it is used to resume after a disconnect.
  • engine: the fingerprint of the computation that serves a subscription, given in subscribed. Keep it with the cursor to resume.
  • topic: the identifier of the stream a subscription follows, given in subscribed.
  • tick: the minimum price increment of a contract. Prices are sent in ticks.
  • tickSizeNanos: the tick size in billionths of a point, as a string: "250000000" is 0.25 points.
  • timestamp: a time in nanoseconds since January 1, 1970 UTC, sent as a string (ts, start, end…).
  • reception time: the time our servers received a trade, shortly after it was executed. from and to bound reception times, and a history day is a UTC day of reception.
  • timeframe: the duration of a bar, in seconds.
  • order flow: reading executed orders and their aggressor side, buyer or seller.
  • delta: ask volume minus bid volume, that is aggressive buying minus aggressive selling.
  • POC (Point of Control): the most traded price.
  • value area: the price zone around the POC that holds a given share of the volume (70% with the generic defaults).
  • imbalance: a marked imbalance between buyers and sellers at a price.
  • RTH (Regular Trading Hours): a product’s regular session; for NQ and ES, the US cash session, from 09:30 to 16:00 New York time.
  • session: from 18:00 to 17:00 the next day, New York time.
  • trading week: from Saturday 00:00 UTC; its first trade comes at the Sunday 18:00 reopen, New York time.
  • default value: the value a parameter you omit takes: the ticker default, otherwise the generic default (see Default values).
  • compute unit: the cost unit of history, 1 per trade in the requested range.
  • Sandbox: the free permissions of every account: a stream delayed by 10 minutes and the last 7 days of history.
  • custom configuration: a distinct combination of contract, indicator and parameters used by your WebSocket subscriptions, whose parameters differ from the current defaults of its ticker. Subscriptions that use only default values do not count. Each plan allows a set number of them at a time (see Limits).

REST API reference

The OpenAPI 3.1 description of the REST API is served at https://api.fathomcharts.com/docs/json, with a Swagger UI at https://api.fathomcharts.com/docs. It gives the schema of every endpoint, request and response.

With your AI assistant

Every page is also available as Markdown for Claude, ChatGPT or your coding agent, indexed in /llms.txt. See Use with an LLM.

Try it for free

The Sandbox is free: a stream delayed by 10 minutes and the last 7 days of history (the 7 × 24 hours before your request), enough to build your whole integration. The Live plan adds real-time data, with the last 7 days of history unlimited. The Historical plan gives lifetime access to the full history, for as long as we operate the historical API (see the terms of sale). You can combine both. See Plans and billing, then get going with the quickstart.