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; the behaviour the four SDKs share is in SDKs.

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, named after its id (big-trades → BigTradesParams, BigTradesData), plus IndicatorParams, IndicatorData and IndicatorId. The catalog descriptions become JSDoc comments. The generator also takes the catalog URL directly: npx fathom-charts-types https://api.fathomcharts.com/v1/indicators src/fathom-charts-types.ts; 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, engine } 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 (subscribed, snapshot, upsert, remove, status, reset, notice): see Events. An error on the subscription ends the loop: for await throws a FathomChartsError carrying the received code.

Subscription

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

Connection lifecycle

The connection opens on the first subscribe() and closes (1000, idle) when the last subscription closes; stream.close() closes everything, and a subscribe() after it throws CLOSED. connectionState is idle, connecting, open, reconnecting or closed. Reconnection, resuming and close codes: see Connection lifecycle. To resume after your process restarts, save sub.cursor and sub.engine and subscribe again with from: { cursor, engine }: see Resume after a restart.

Maintenance windows

stream.maintenance lists the maintenance windows announced on the connection and not over, by start: { id, startsAt, endsAt, message } (times in nanoseconds, as strings). Every new connection receives the windows already announced. See Updates and maintenance.

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. A resume refused with CURSOR_EXPIRED means the computation changed since the export started: the lines already received cannot be continued, start the export again.

Rate limit and retries

rateLimitRetries bounds the retries described in Rate limit and retries. An AbortSignal ends a call, and the wait for a retry, right away (ABORTED).

Errors

Every error the SDK throws, or ends a loop with, is a FathomChartsError; the error it stems from, if any, is its cause. Its fields:

The codes, the API’s and the SDK’s own, are listed in Errors (exported as ERROR_CODES; the WebSocket close codes, as CloseCode). CONFIGURATION also covers, in TypeScript, the ws package missing for an API key, no WebSocket implementation, and zstd decompression missing for exportNdjson().

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