TypeScript SDK

@fathom-charts/sdk handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination, exports and rate-limit retries for you. This page describes every option and method.

Install

npm install @fathom-charts/sdk ws

• ESM only: the package ships no CommonJS build. Your project must declare "type": "module" in its package.json (or use .mjs / .mts files).
• Node 22 or later, and browsers. exportNdjson() requires Node 22.15 or later (zstd decompression from node:zlib).
• ws is only needed in Node: it opens the connection with the Authorization header. In a browser, the SDK uses the native WebSocket with a stream token, and never imports ws.

The SDK imports ws dynamically, with the module name in a variable, so that browser bundlers leave it out. Webpack then reports Critical dependency: the request of a dependency is an expression: this warning is harmless.

Indicator types

The SDK is generic: an indicator’s data is typed by the types you generate from the catalog (GET /v1/indicators, no authentication).

curl https://api.fathomcharts.com/v1/indicators -o catalog.json
npx fathom-charts-types catalog.json src/fathom-charts-types.ts

The generated file exports, for each indicator, <Name>Params and <Name>Data (BigTradesData, FootprintData…), plus IndicatorParams, IndicatorData and IndicatorId. The catalog descriptions become JSDoc comments; a footprint level is typed [number, number, number, number?] (the 4th element is optional). The output folder is created if it does not exist. Generate the file again when the catalog changes (its engineFingerprint changes with the computation).

Real time: FathomChartsStream

import { FathomChartsStream } from '@fathom-charts/sdk';
import type { BigTradesData } from './fathom-charts-types.js';

const stream = new FathomChartsStream({
  url: 'wss://stream.fathomcharts.com/v1',
  apiKey: process.env.FATHOM_CHARTS_API_KEY!,
  onStateChange: (state) => console.log('connection', state),
});

const sub = stream.subscribe<BigTradesData>({
  instrument: 'NQ.front',
  indicator: 'big-trades',
  params: { minimum: 30 },
  mode: 'confirmed',
});

for await (const event of sub) {
  if (event.type === 'upsert') console.log(event.cursor, event.data.side, event.data.volume);
}

Options

subscribe()

stream.subscribe<D>(options) opens a subscription and returns a Subscription object, to read with for await. Its options are those of the subscribe message: instrument, indicator, params ({} by default), mode (live by default) and from ("live" by default, { cursor } or { time }). The SDK picks the sub name itself. The type D is the indicator’s data type (BigTradesData…).

The loop receives events whose type field is the name of the server message, without the sub field:

The other server messages do not become events: the SDK handles hb (silent connection detection, resume cursor), pong and notice (passed to onNotice) itself. An error on the subscription ends the loop: for await throws a FathomChartsError carrying the received code (INVALID_PARAMETERS, UNKNOWN_INSTRUMENT, FORBIDDEN, QUOTA_EXCEEDED, NOT_COVERED…).

The SDK drops duplicates: after a resume, no upsert or remove whose cursor is not strictly greater than the last one received is handed to you.

Subscription

Leaving the loop (break, return or an exception in its body) calls close().

Connection lifecycle

All the subscriptions of a FathomChartsStream share one connection, which counts against the connections of your plan:

• the connection opens on the first subscribe();
• when the last subscription closes (break, close(), or a server error on the last subscription), the SDK closes the connection (code 1000, reason idle) and connectionState becomes idle. A new subscribe() opens it again;
• stream.close() closes every subscription and the connection. Calling it right after subscribe(), before the connection is open, is safe. A subscribe() after close() throws CLOSED;
• connectionState is idle, connecting, open, reconnecting or closed.

After a disconnect, the SDK reconnects with exponential backoff and jitter, and sends each subscribe again with from: { cursor }, the last cursor received: you receive subscribed and status again, then the missed messages, with no snapshot when the resume succeeds, or a reset followed by a snapshot otherwise. A from: { time } subscription that already received a cursor resumes from that cursor: the past range is never replayed a second time. Only a disconnect during warming, before the first cursor, starts it again from the original time, and the part replayed from history is then charged again.

After one of these final errors, a new subscribe() on the same FathomChartsStream throws the same error: fix the cause, then create a new FathomChartsStream.

Resume after a restart

The SDK resumes on its own after a disconnect, as long as your process runs. To resume after your process restarts, save sub.cursor as you go (along with the state you built from it), then open the subscription again with from: { cursor }:

import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { FathomChartsStream } from '@fathom-charts/sdk';
import type { BigTradesData } from './fathom-charts-types.js';

// A file here; in production, the storage of your state (a database…).
const CURSOR_FILE = 'big-trades.cursor';
const saved = existsSync(CURSOR_FILE) ? readFileSync(CURSOR_FILE, 'utf8') : undefined;

const stream = new FathomChartsStream({
  url: 'wss://stream.fathomcharts.com/v1',
  apiKey: process.env.FATHOM_CHARTS_API_KEY!,
});

const sub = stream.subscribe<BigTradesData>({
  instrument: 'NQ.front',
  indicator: 'big-trades',
  params: { minimum: 30 },
  mode: 'confirmed',
  from: saved ? { cursor: saved } : 'live',
});

for await (const event of sub) {
  if (event.type === 'upsert') console.log(event.data.side, event.data.volume);
  // The cursor is saved once the event is handled.
  if (sub.cursor) writeFileSync(CURSOR_FILE, sub.cursor);
}

If the cursor is too old, you receive a reset then a new snapshot: start over from it.

History: FathomChartsRest

import { FathomChartsRest } from '@fathom-charts/sdk';

const rest = new FathomChartsRest({ baseUrl: 'https://api.fathomcharts.com', apiKey: process.env.FATHOM_CHARTS_API_KEY! });

Methods

Every method that reads history takes the query described on the History page (instrument, indicator, params, from, to, mode, and depending on the method limit, cursor, untilCursor, snapshot), and an optional AbortSignal.

The options of exportNdjson(): signal, maxResumes (consecutive resumes without a new line before giving up, 5 by default) and resumeDelayMs (delay before the first resume, 1 s by default, doubled on each consecutive resume up to 30 s). If the very first request fails (network error or 5xx before the X-Export-Token header), exportNdjson() never sends it again: a new export would be charged again. It throws the error, and you decide.

Rate limit and retries

A 429 RATE_LIMITED is retried up to rateLimitRetries times: after the delay of the Retry-After header (60 seconds at most), or, without that header, after 1, 2, then 4 seconds. An AbortSignal ends the wait right away. 429 QUOTA_EXCEEDED (monthly budget used up) is never retried: it is thrown at once.

Errors

Every SDK error is a FathomChartsError:

SDK codes, in addition to the API codes (the full list is exported as ERROR_CODES):

A 4001 close gives UNAUTHORIZED, with a message listing the possible causes (key missing, malformed, unknown, revoked or expired, stream token invalid, expired or already used).

Cursors

compareCursors(a, b) compares two cursors <utcDay>.<rank>.<k> number by number and returns a negative number, zero or a positive number. A malformed cursor (numbers with leading zeros, a missing field…) throws INVALID_PARAMETERS.

import { compareCursors } from '@fathom-charts/sdk';

compareCursors('20720.111416.0', '20720.111417.0'); // < 0