# 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](#glossary) defines every term these pages use: cursor, snapshot, tick, front month, the several meanings of “live”…

- [Quickstart](https://fathomcharts.com/docs/quickstart.md): From API key to first message in a few minutes.
- [Authentication](https://fathomcharts.com/docs/authentication.md): API keys and browser access.
- [Real time](https://fathomcharts.com/docs/websocket.md): Subscribe, keep your data in sync, resume after a disconnect.
- [History](https://fathomcharts.com/docs/history.md): Compute an indicator over a past period.
- [Exports](https://fathomcharts.com/docs/exports.md): Download a long period as a single file.
- [Indicators](https://fathomcharts.com/docs/indicators.md): Parameters and data for every indicator.

## 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](#front-month));
- an **indicator** from the [catalog](https://fathomcharts.com/docs/indicators.md): `big-trades`, `footprint`, `liquidity-walls`…;
- its **parameters**: parameters you omit take their [default values](#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](https://fathomcharts.com/account) (see [Authentication](https://fathomcharts.com/docs/authentication.md)). A key (`fc_live_…`) has the rights of your [plans](https://fathomcharts.com/docs/billing.md): 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](https://fathomcharts.com/docs/authentication.md#browser-access) 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](https://fathomcharts.com/docs/websocket.md#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](#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 `id`s) 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](https://fathomcharts.com/docs/indicators.md) 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](https://fathomcharts.com/docs/authentication.md#scopes-and-restrictions). 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"
    }
  ]
}
```

| Field           | Content                                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `symbol`        | The contract symbol, to pass as `instrument`.                                                                                                                                              |
| `alias`         | The alias that designates this contract today (`NQ.front`), or `null`.                                                                                                                     |
| `tickSizeNanos` | The tick size in billionths of a point (units of 10⁻⁹), as a string: `"250000000"` = 0.25.                                                                                                 |
| `status`        | The state of the instrument’s data: `live`, `warming`, `source_delayed`, `source_down` or `market_closed` (see [Stream status](https://fathomcharts.com/docs/websocket.md#stream-status)). |
| `updatedAt`     | When 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](https://fathomcharts.com/docs/history.md#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](https://fathomcharts.com/docs/maintenance.md#maintenance-notices):

```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.

| What                              | Clock         | Boundaries                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session                           | New York time | From 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 week                      | UTC           | Starts 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.                                                                                                                                             |
| Bars                              | Session open  | A 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 days | UTC           | Timestamps count from January 1, 1970 UTC. The day of a [cursor](#cursors) and the days that [history](https://fathomcharts.com/docs/history.md#available-range) 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 UTC               | Sunday 23:00 UTC                 |
| US cash open (09:30 New York time)                        | 13:30 UTC                        | 14:30 UTC                        |
| Daily break (17:00 to 18:00 New York time)                | 21:00 to 22:00 UTC               | 22:00 to 23:00 UTC               |
| Midnight UTC, when a new day of history becomes available | 20:00 New York time              | 19: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 `id`s 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 `id`s 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 `id`s 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](https://fathomcharts.com/docs/websocket.md#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](https://fathomcharts.com/docs/websocket.md#starting-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](https://fathomcharts.com/docs/websocket.md#cursors-and-resuming), and their [format](https://fathomcharts.com/docs/history.md#cursors).

## 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](https://fathomcharts.com/docs/maintenance.md)):

- an update of the [default values](#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](https://fathomcharts.com/docs/maintenance.md#maintenance-notices).

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](https://fathomcharts.com/docs/indicators.md) 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](https://fathomcharts.com/docs/limits.md#how-limits-are-counted).

## Displaying on a chart

- **Prices**: convert ticks to points as explained in [Prices and timestamps](#prices-and-timestamps). Do not round computed prices (VWAP, `MP` level…).
- **Time**: convert timestamps with `BigInt` (see [Prices and timestamps](#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](#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](https://fathomcharts.com/docs/websocket.md#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](#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](https://fathomcharts.com/docs/limits.md#how-limits-are-counted)).

## REST API reference

The OpenAPI 3.1 description of the REST API is served at [`https://api.fathomcharts.com/docs/json`](https://api.fathomcharts.com/docs/json), with a Swagger UI at [`https://api.fathomcharts.com/docs`](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`](https://fathomcharts.com/llms.txt). See [Use with an LLM](https://fathomcharts.com/docs/llm.md).

## 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](https://fathomcharts.com/terms-of-sale#7-term-cancellation-and-end-of-access)). You can combine both. See [Plans and billing](https://fathomcharts.com/docs/billing.md), then get going with the [quickstart](https://fathomcharts.com/docs/quickstart.md).
