SDKs

SDKs

Four SDKs, one behaviour. Each handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination, exports and rate-limit retries for you. Pick your language in any code block: the whole documentation follows your choice, except a few TypeScript-only pages (the raw WebSocket client, the browser examples, the stream token route of Authentication included, Chart integration and Trading bot).

LanguagePackageRuns onReference
TypeScript@fathom-charts/sdk (npm)Node 22.15+, browsersTypeScript SDK
Pythonfathom-charts (PyPI)Python 3.11+, asyncioPython SDK
C#FathomCharts (NuGet).NET 8+, and .NET Framework 4.8 through .NET Standard 2.0 (the type generator needs the .NET 10 SDK)C# SDK
Rustfathom-charts (crates.io)Rust 1.88+, TokioRust SDK

Install

terminal
npm install @fathom-charts/sdk@0.6.0 ws
terminal
pip install fathom-charts==0.6.0
terminal
dotnet add package FathomCharts --version 0.6.0
terminal
cargo add fathom-charts@0.6.0
cargo add tokio --features full
cargo add futures serde serde_json --features serde/derive

In Python, install the package in a virtual environment, as in the Quickstart: the fathom-charts-types command below is on the PATH once the environment is activated, and the environment’s Python runs it without activating it: .venv/bin/python -m fathom_charts.generate_types … (Windows: .venv\Scripts\python).

Indicator types

Each SDK generates, from the catalog (GET /v1/indicators, no authentication), the types of every indicator’s parameters and data: <Name>Params and <Name>Data, named after its id (big-trades → BigTradesParams, BigTradesData), with the catalog’s descriptions as doc comments. Generate them again when the catalog changes (its engineFingerprint changes with the computation), with the generator of the SDK version you use: the commands below pin it to version 0.6.0, the version these pages describe; change the version when you use another one (in Python, the generator is installed with the package, so it is always the version you use). In TypeScript, the pin also makes sure npx runs the generator of @fathom-charts/sdk, never a package of another publisher with the same command name. The generator writes the file, prints nothing and exits with code 0; with wrong arguments, it prints its usage and exits with code 2; on a failure, it prints one line and exits with code 1. --help prints the usage.

An indicator that publishes several kinds of objects (Fathom Zones, Fathom Opening) gets one type per kind, and the id of an object tells its kind (bar:…, zone:…). Each language shapes them its own way: a union of one type per kind in TypeScript and Python, an untagged enum with one variant per kind in Rust, one flat record whose properties of the other kinds are null in C#. Each SDK’s reference shows how to tell them apart.

terminal
npx -p @fathom-charts/sdk@0.6.0 fathom-charts-types https://api.fathomcharts.com/v1/indicators src/fathom-charts-types.ts
terminal
fathom-charts-types https://api.fathomcharts.com/v1/indicators fathom_charts_types.py
terminal
dotnet dnx FathomCharts.Types@0.6.0 https://api.fathomcharts.com/v1/indicators FathomChartsTypes.cs
terminal
cargo install fathom-charts@0.6.0 --features cli --locked
fathom-charts-types https://api.fathomcharts.com/v1/indicators src/fathom_charts_types.rs

A first stream

Large aggressive orders of at least 30 contracts on the front-month NQ contract, completed orders only. The key is read from the FATHOM_CHARTS_API_KEY environment variable (see the Quickstart).

minimum: 30 is set explicitly. The current NQ default of minimum is different (see Fathom Trades), so this subscription uses a custom configuration: a combination of parameters that differs from the defaults of its ticker. The Sandbox allows one at a time, released when the subscription closes. To use the defaults instead, leave out params; explicit values keep the results identical when we update the defaults.

Prices arrive in ticks, and times in nanoseconds since January 1, 1970 UTC, as strings. The example converts each in one line: the price in points is ticks × tickSizeNanos / 10⁹, with the tickSizeNanos of the subscribed event (see Prices and timestamps).

src/big-trades.ts
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!,
});

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

let tickSizeNanos = 0;
for await (const event of bigTrades) {
  if (event.type === 'subscribed') tickSizeNanos = Number(event.tickSizeNanos);
  if (event.type === 'snapshot') console.log('snapshot', event.items.length, 'objects');
  if (event.type === 'status') console.log('status', event.state);
  if (event.type === 'upsert') {
    const price = (event.data.price * tickSizeNanos) / 1e9;
    const time = new Date(Number(BigInt(event.ts) / 1_000_000n));
    console.log(time.toISOString(), event.data.side, event.data.volume, price);
  }
}
big_trades.py
import asyncio
import os
from datetime import UTC, datetime

from fathom_charts import FathomChartsStream, Snapshot, Status, Subscribed, Upsert
from fathom_charts_types import BigTradesData


async def main() -> None:
    async with FathomChartsStream(url="wss://stream.fathomcharts.com/v1", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as stream:
        tick_size_nanos = 0
        async with stream.subscribe(
            instrument="NQ.front",
            indicator="big-trades",
            params={"minimum": 30},
            mode="confirmed",
            data=BigTradesData,
        ) as big_trades:
            async for event in big_trades:
                match event:
                    case Subscribed():
                        tick_size_nanos = int(event.tick_size_nanos)
                    case Snapshot():
                        print("snapshot", len(event.items), "objects")
                    case Status():
                        print("status", event.state)
                    case Upsert():
                        price = event.data["price"] * tick_size_nanos / 1e9
                        time = datetime.fromtimestamp(int(event.ts) / 1e9, UTC)
                        print(time.isoformat(), event.data["side"], event.data["volume"], price)
                    case _:
                        pass


asyncio.run(main())
Program.cs
using FathomCharts;
using FathomCharts.Indicators;

await using var stream = new FathomChartsStream(new StreamOptions
{
    Url = "wss://stream.fathomcharts.com/v1",
    ApiKey = Environment.GetEnvironmentVariable("FATHOM_CHARTS_API_KEY"),
});

var bigTrades = stream.Subscribe<BigTradesData>(new SubscribeOptions
{
    Instrument = "NQ.front",
    Indicator = IndicatorIds.BigTrades,
    Params = new BigTradesParams { Minimum = 30 },
    Mode = Mode.Confirmed,
});

long tickSizeNanos = 0;
await foreach (var e in bigTrades)
{
    switch (e)
    {
        case Subscribed subscribed:
            tickSizeNanos = long.Parse(subscribed.TickSizeNanos);
            break;
        case Snapshot<BigTradesData> snapshot:
            Console.WriteLine($"snapshot {snapshot.Items.Count} objects");
            break;
        case Status status:
            Console.WriteLine($"status {status.State}");
            break;
        case Upsert<BigTradesData> upsert:
            var price = upsert.Data.Price * tickSizeNanos / 1e9;
            var time = DateTimeOffset.FromUnixTimeMilliseconds(long.Parse(upsert.Ts) / 1_000_000);
            Console.WriteLine($"{time:O} {upsert.Data.Side} {upsert.Data.Volume} {price}");
            break;
    }
}
src/main.rs
use std::time::{Duration, UNIX_EPOCH};

use fathom_charts::{FathomChartsStream, Mode, StreamEvent, SubscribeOptions};
use futures::StreamExt;
use serde_json::json;

mod fathom_charts_types;
use fathom_charts_types::BigTradesData;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let stream = FathomChartsStream::builder("wss://stream.fathomcharts.com/v1")
        .api_key(std::env::var("FATHOM_CHARTS_API_KEY").map_err(|_| "FATHOM_CHARTS_API_KEY is not set")?)
        .build()?;

    let mut big_trades = stream.subscribe::<BigTradesData>(
        SubscribeOptions::new("NQ.front", "big-trades")
            .params(json!({ "minimum": 30 }))
            .mode(Mode::Confirmed),
    )?;

    let mut tick_size_nanos = 0.0;
    while let Some(event) = big_trades.next().await {
        match event? {
            StreamEvent::Subscribed(subscribed) => tick_size_nanos = subscribed.tick_size_nanos.parse()?,
            StreamEvent::Snapshot(snapshot) => println!("snapshot {} objects", snapshot.items.len()),
            StreamEvent::Status(status) => println!("status {}", status.state),
            StreamEvent::Upsert(upsert) => {
                let price = upsert.data.price as f64 * tick_size_nanos / 1e9;
                // A SystemTime: a date crate (chrono, time) formats it.
                let time = UNIX_EPOCH + Duration::from_nanos(upsert.ts.parse()?);
                println!("{time:?} {} {} {price}", upsert.data.side, upsert.data.volume);
            }
            _ => {}
        }
    }
    Ok(())
}

After the snapshot and status lines, nothing more is printed until the next large order of 30 contracts or more. Outside US cash hours (09:30 to 16:00 New York time), several minutes can go by without one: the program is not stuck, the status line already shows that the stream works. While the market is closed, the status is market_closed. Every SDK prints the state as on the wire (live).

Events

A subscription hands you events named after the messages of the protocol, without the sub field. The fields are those of the message, in your language’s naming convention (tickSizeNanos, tick_size_nanos, TickSizeNanos).

EventFieldsWhen
subscribedtopic, instrument, tickSizeNanos, engineThe subscription is accepted. Arrives again after every reconnection, and before a reset with reason roll, entitlement_changed or engine_change.
snapshotcursor, items (each id, final, ts, data)The starting state. Replace your whole local state with items.
upsertcursor, id, final, ts, dataObject id is created or entirely replaced.
removecursor, id, final, tsObject id is deleted.
statusstate, lagMsThe stream status (see Stream status). Arrives again after every reconnection.
resetreasonYour local state is no longer valid: discard it, a snapshot follows.
noticekind, id, effectiveAt, endsAt, message (depending on kind)A notice to the connection, given to each of its subscriptions: a restart, or a maintenance window announced or cancelled. Nothing to do: the SDK reconnects and resumes by itself. See Updates and maintenance.
retryingcode, message, delayMsA transient error on our side (UPSTREAM_ERROR, CAPACITY, INTERNAL, SOURCE_DOWN) ended the subscription on the server. Nothing to do: the SDK subscribes it again in delayMs milliseconds, from the last cursor received, and subscribed follows.

Events come in this order:

  • a new subscription: subscribed, a status with state warming when the stream is still being prepared, snapshot, then status (live, for example);
  • a subscription that starts in the past (from a time): subscribed, a warming status when the stream is still being prepared, the snapshot at that time, the upsert and remove events replayed since then, then status live once the replay has caught up with live data, and live events after it;
  • a resume: subscribed, the missed upsert and remove events, then status, without a snapshot;
  • a change of computation or contract: subscribed, reset, snapshot, then status.

The SDK handles hb (silent connection detection, resume cursor) and pong itself. An error on the subscription with a transient code (UPSTREAM_ERROR, CAPACITY, INTERNAL, SOURCE_DOWN) does not end it: the SDK hands you retrying, then subscribes it again after a backoff of its own (0.5 s, doubling up to 30 s, with jitter; back to 0.5 s once subscribed arrives), from the last cursor received, so you miss nothing. Meanwhile the subscription stays open and keeps the connection. Any other error on the subscription ends its loop with the SDK’s error, carrying the received code (INVALID_PARAMETERS, UNKNOWN_INSTRUMENT, UNKNOWN_INDICATOR, FORBIDDEN, QUOTA_EXCEEDED, NOT_COVERED, or a code your SDK version does not know). The SDK drops duplicates: after a resume or a retry, only the upsert and remove events whose cursor is strictly greater than the last one received are handed to you.

Values your SDK version does not know. A field with a set list of values can get a new one: the state of status, the reason of reset, the kind of notice, the string enums of the generated indicator types (side…) and of the REST answers (plan, engine.state…). Every SDK hands you such a value as it is, without dropping the event or failing:

  • TypeScript and Python: the string itself. Their types list the known values and accept any other string (TypeScript: … | (string & {}));
  • C#: a record of the same type, built from the text (new SourceState("halted")). The known values are its static properties (SourceState.Live): compare with ==, and ToString() gives the text as on the wire;
  • Rust: the Other(String) variant of the enum (SourceState::Other("halted")); {} prints the text as on the wire.

Keep a default branch for them. An unknown reset reason is still a reset: discard the state, a snapshot follows.

Keep a state by id

Every object has a stable id. Keep the objects of a subscription in a map keyed by id, and apply each event to it:

  • snapshot: replace everything with its items;
  • upsert: create object id, or replace it entirely (an upsert carries the whole object, never a difference);
  • remove: delete object id;
  • reset: clear everything; a snapshot follows.

An object in progress comes back under the same id at each change, with final: false, each version replacing the previous one. Its last version has final: true: its data no longer changes, but a remove can still delete it (a key-levels level that leaves the window, for example). In confirmed mode, you only receive the final versions. Here, in live mode (the default), the orders in progress come too:

src/state.ts
import { FathomChartsStream, type Item } 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!,
});

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

const objects = new Map<string, Item<BigTradesData>>();
for await (const event of sub) {
  switch (event.type) {
    case 'snapshot':
      objects.clear();
      for (const item of event.items) objects.set(item.id, item);
      break;
    case 'upsert':
      objects.set(event.id, { id: event.id, final: event.final, ts: event.ts, data: event.data });
      console.log(event.final ? 'final' : 'in progress', event.id, event.data.volume);
      break;
    case 'remove':
      objects.delete(event.id);
      break;
    case 'reset':
      objects.clear();
      break;
  }
}
state.py
import asyncio
import os

from fathom_charts import FathomChartsStream, Item, Remove, Reset, Snapshot, Upsert
from fathom_charts_types import BigTradesData


async def main() -> None:
    objects: dict[str, Item[BigTradesData]] = {}
    async with FathomChartsStream(url="wss://stream.fathomcharts.com/v1", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as stream:
        async with stream.subscribe(instrument="NQ.front", indicator="big-trades", params={"minimum": 30}, data=BigTradesData) as sub:
            async for event in sub:
                match event:
                    case Snapshot():
                        objects = {item.id: item for item in event.items}
                    case Upsert():
                        objects[event.id] = Item(event.id, event.final, event.ts, event.data)
                        print("final" if event.final else "in progress", event.id, event.data["volume"])
                    case Remove():
                        objects.pop(event.id, None)
                    case Reset():
                        objects.clear()
                    case _:
                        pass


asyncio.run(main())
Program.cs
using FathomCharts;
using FathomCharts.Indicators;

await using var stream = new FathomChartsStream(new StreamOptions
{
    Url = "wss://stream.fathomcharts.com/v1",
    ApiKey = Environment.GetEnvironmentVariable("FATHOM_CHARTS_API_KEY"),
});

var sub = stream.Subscribe<BigTradesData>(new SubscribeOptions
{
    Instrument = "NQ.front",
    Indicator = IndicatorIds.BigTrades,
    Params = new BigTradesParams { Minimum = 30 },
});

var objects = new Dictionary<string, Item<BigTradesData>>();
await foreach (var e in sub)
{
    switch (e)
    {
        case Snapshot<BigTradesData> snapshot:
            objects.Clear();
            foreach (var item in snapshot.Items) objects[item.Id] = item;
            break;
        case Upsert<BigTradesData> upsert:
            objects[upsert.Id] = new Item<BigTradesData>(upsert.Id, upsert.Final, upsert.Ts, upsert.Data);
            Console.WriteLine($"{(upsert.Final ? "final" : "in progress")} {upsert.Id} {upsert.Data.Volume}");
            break;
        case Remove remove:
            objects.Remove(remove.Id);
            break;
        case Reset:
            objects.Clear();
            break;
    }
}
src/main.rs
use std::collections::HashMap;

use fathom_charts::{FathomChartsStream, Item, StreamEvent, SubscribeOptions};
use futures::StreamExt;
use serde_json::json;

mod fathom_charts_types;
use fathom_charts_types::BigTradesData;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let stream = FathomChartsStream::builder("wss://stream.fathomcharts.com/v1")
        .api_key(std::env::var("FATHOM_CHARTS_API_KEY").map_err(|_| "FATHOM_CHARTS_API_KEY is not set")?)
        .build()?;

    let mut sub = stream.subscribe::<BigTradesData>(SubscribeOptions::new("NQ.front", "big-trades").params(json!({ "minimum": 30 })))?;

    let mut objects: HashMap<String, Item<BigTradesData>> = HashMap::new();
    while let Some(event) = sub.next().await {
        match event? {
            StreamEvent::Snapshot(snapshot) => objects = snapshot.items.into_iter().map(|item| (item.id.clone(), item)).collect(),
            StreamEvent::Upsert(upsert) => {
                println!("{} {} {}", if upsert.is_final { "final" } else { "in progress" }, upsert.id, upsert.data.volume);
                objects.insert(upsert.id.clone(), Item { id: upsert.id, is_final: upsert.is_final, ts: upsert.ts, data: upsert.data });
            }
            StreamEvent::Remove(remove) => {
                objects.remove(&remove.id);
            }
            StreamEvent::Reset(_) => objects.clear(),
            _ => {}
        }
    }
    Ok(())
}

A large order in progress prints in progress lines under one id, then a final line under the same id. The same map, saved with the cursor and the engine, lets you resume after a restart.

Connection lifecycle

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

  • the connection opens on the first subscription;
  • when the last subscription closes (leaving its loop, or in Python its async with block; closing it; or a server error on it that is not retried), the SDK closes the connection (code 1000, reason idle) and the connection state becomes idle. A new subscription opens it again;
  • closing the stream closes every subscription and the connection. Doing it right after subscribing, before the connection is open, is safe. A subscription after that throws CLOSED;
  • the connection state is idle, connecting (opening from idle), open, reconnecting (from the moment a connection drops, whoever closed it, until a new one opens) or closed (the stream was closed, or a final error ended every subscription);
  • stream.lastClosestream.last_closestream.LastClosestream.last_close() gives the code and reason of the last close of an open connection: the server’s close frame (4029 TOO_MANY_CONNECTIONS when every connection of your plan is in use, for example), 1005 for a close frame without a code, 1006 when the connection was lost without one, or the SDK’s own close (4000 heartbeat timeout or client buffer full before it reconnects; 1000 idle when the last subscription closed, client closed when you closed the stream while the connection was still open, failed after a final error). Closing the stream after its last loop has ended leaves 1000 idle: the connection was already closed. It is set before the state changes: when the state becomes reconnecting, it tells why. It is empty until a connection closes, and an attempt that fails before the connection opens leaves it as it is.

After a disconnect, the SDK reconnects with exponential backoff and jitter, and subscribes again from the last cursor received: you receive subscribed again, then the missed messages and a status when the resume succeeds (no snapshot), or a reset followed by a snapshot and a status otherwise. The resume succeeds from the stream’s memory of about 15 minutes, or beyond it from history when your rights cover the cursor’s UTC day (see Cursors and resuming); beyond your plan’s depth, it does not succeed once that memory is exceeded. A subscription that started in the past (from a time) and 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 (the part before midnight UTC today: the current UTC day is not charged).

The SDK reconnects silently: while it retries, the loop receives nothing, so a stream that cannot reconnect (network down, a wrong host name, a token server that cannot be reached) looks like a quiet market. Watch onStateChangeon_state_changeOnStateChangeon_state_change to show or log it: it is called with reconnecting when a connection drops, and lastCloselast_closeLastCloselast_close() then tells why. Each SDK’s reference has an example.

A streamTokenstream_tokenStreamTokenstream_token function (an application distributed to end users, which must not hold the key) is called before every connection. When it fails with a network failure raised before any answer, or with an SDK error whose code is NETWORK_ERROR, RATE_LIMITED, CAPACITY or HTTP_429, or whose status is 500 or more, the SDK calls it again with the reconnection backoff. Any other error, a bug in the function included, ends every subscription: an SDK error as it is (QUOTA_EXCEEDED, although its status is 429, for example), any other error as CONFIGURATION. A network failure is, in TypeScript, the TypeError thrown by fetch itself or a TimeoutError; in Python, an OSError (TimeoutError included) or an httpx.TransportError; in C#, an HttpRequestException without an answer, an IOException, a SocketException or a timeout; in Rust, an I/O error, a reqwest error without a status or an elapsed tokio::time::timeout. An HTTP client’s error for an answer received is not one: to have a busy token server retried, throw an SDK error with its status (HTTP_502, status 502, for example).

Close codeWhat the SDK does
4001Ends every subscription with UNAUTHORIZED, without reconnecting: the connection was refused when it opened. The message lists the possible causes: key missing, malformed, unknown, revoked or expired, stream token invalid, expired or already used.
4003Ends every subscription with KEY_REVOKED (the key was revoked or expired during an open connection), ENTITLEMENTS_CHANGED or FORBIDDEN, depending on the close reason, without reconnecting.
1002, 1003, 1007, 1009Ends every subscription with an error whose code is the close reason, as our server sends it (PROTOCOL_ERROR, BINARY_NOT_SUPPORTED, INVALID_UTF8 or MESSAGE_TOO_BIG), or PROTOCOL_ERROR when the close has no reason: the same messages would be refused again.
4029Retries, at least 5 seconds apart, for 120 seconds by default (the attempt in progress at the end of that period finishes first), then ends everything with TOO_MANY_CONNECTIONS. The wait covers a connection of yours that was lost without a close: the server usually frees it when you reconnect, if it does not answer a ping within 2 seconds, otherwise after 30 seconds of silence, or about 90 seconds if our server stopped. Meanwhile the loop receives nothing. Each attempt opens a connection that the server then closes with 4029, so the connection state goes from open to reconnecting at every attempt.
4008Reconnects right away and resumes from the last cursor. When the new connection is closed with 4008 again before the subscriptions are accepted, the next attempts wait with backoff.
1008, 1011, 1012, 1013Reconnects with backoff and resumes from the last cursor: too many messages from the client (1008, see Limits), an internal error (1011), a restart of the server, announced by a notice of kind reconnect (1012, see Updates and maintenance), or a server that asks to come back later (1013: at least 1 second later).
Others (1006 for a connection lost without a close frame), or 15 seconds without a messageReconnects with backoff. The SDK checks for silence every third of that delay, so it notices it between 15 and 20 seconds. When the SDK drops the connection itself (silence, a full buffer), it closes it with code 4000, and the state becomes reconnecting at once.
HTTP 4xx at the opening (other than 429)Ends every subscription with HTTP_<status>, without reconnecting: a wrong URL path, for example. In TypeScript, only with the ws package: browsers and Node’s built-in WebSocket hide the status, and the SDK keeps retrying.

After one of these final errors, a new subscription on the same stream throws the same error: fix the cause, then create a new stream.

Flow control follows the same rules in every SDK. Above 10,000 events waiting to be read (all subscriptions together), the SDK stops reading the socket, which slows the server down: the server then keeps only the latest version of each object in progress (see Backpressure). While it waits, the SDK sends ping messages so that the server keeps the connection, and it reads again once the events waiting fall to half of that threshold. Above the threshold, an event that arrives anyway replaces the waiting provisional version of the same object: intermediate versions of an object in progress may be skipped, final versions and removals never are. How many intermediate versions are skipped differs between SDKs, as each stops reading in its own way: with a slow consumer, the TypeScript SDK merges more of them in its own queue than the Python SDK, which leaves more of them in the buffers of its socket and of the network. None skips a final version or a removal.

Where the socket cannot be paused (browsers), the SDK keeps reading and, at 40,000 events waiting, closes the connection (4000 client buffer full; the state becomes reconnecting at once). It reopens it once the events waiting fall to half of the 10,000 threshold, and resumes from the last cursor received: nothing is lost. A consumer that stays slower than the stream keeps closing and reopening the connection: handle the events quickly, or hand the slow work to another task. The options are in each SDK’s reference.

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 three things together as you go: the subscription’s cursor, its engine, and the state you built from the events (the map of Keep a state by id). At start, load them, and subscribe again from that cursor and that engine:

src/big-trades.ts
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { FathomChartsStream, type Item } 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 STATE_FILE = 'big-trades.state.json';
interface Saved { cursor: string; engine: string; items: Item<BigTradesData>[] }
const saved = existsSync(STATE_FILE) ? JSON.parse(readFileSync(STATE_FILE, 'utf8')) as Saved : undefined;
const objects = new Map((saved?.items ?? []).map((item) => [item.id, item]));

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.cursor, engine: saved.engine } : 'live',
});

for await (const event of sub) {
  if (event.type === 'snapshot') {
    objects.clear();
    for (const item of event.items) objects.set(item.id, item);
  }
  if (event.type === 'upsert') objects.set(event.id, { id: event.id, final: event.final, ts: event.ts, data: event.data });
  if (event.type === 'remove') objects.delete(event.id);
  if (event.type === 'reset') objects.clear();
  // Saved once an event that carries a cursor is applied: the cursor, the engine and the state then belong together.
  if ((event.type === 'snapshot' || event.type === 'upsert' || event.type === 'remove') && sub.cursor && sub.engine) {
    const state: Saved = { cursor: sub.cursor, engine: sub.engine, items: [...objects.values()] };
    writeFileSync(STATE_FILE, JSON.stringify(state));
  }
}
big_trades_resume.py
import asyncio
import json
import os
from pathlib import Path
from typing import Any

from fathom_charts import FathomChartsStream, From, Remove, Reset, Snapshot, SnapshotItem, Upsert
from fathom_charts_types import BigTradesData

# A file here; in production, the storage of your state (a database…).
STATE_FILE = Path("big-trades.state.json")


async def main() -> None:
    saved: dict[str, Any] = json.loads(STATE_FILE.read_text()) if STATE_FILE.exists() else {}
    objects: dict[str, SnapshotItem[BigTradesData]] = {item["id"]: item for item in saved.get("items", [])}
    start: From = {"cursor": saved["cursor"], "engine": saved["engine"]} if saved else "live"
    async with FathomChartsStream(url="wss://stream.fathomcharts.com/v1", api_key=os.environ["FATHOM_CHARTS_API_KEY"]) as stream:
        async with stream.subscribe(
            instrument="NQ.front",
            indicator="big-trades",
            params={"minimum": 30},
            mode="confirmed",
            from_=start,
            data=BigTradesData,
        ) as sub:
            async for event in sub:
                match event:
                    case Snapshot():
                        objects = {i.id: {"id": i.id, "final": i.final, "ts": i.ts, "data": i.data} for i in event.items}
                    case Upsert():
                        objects[event.id] = {"id": event.id, "final": event.final, "ts": event.ts, "data": event.data}
                    case Remove():
                        objects.pop(event.id, None)
                    case Reset():
                        objects.clear()
                    case _:
                        pass
                # Saved once an event that carries a cursor is applied: the cursor, the engine and the state then belong together.
                if isinstance(event, (Snapshot, Upsert, Remove)) and sub.cursor is not None and sub.engine is not None:
                    state = {"cursor": sub.cursor, "engine": sub.engine, "items": list(objects.values())}
                    STATE_FILE.write_text(json.dumps(state))


asyncio.run(main())
Program.cs
using FathomCharts;
using FathomCharts.Indicators;

// A file here; in production, the storage of your state (a database…).
const string StateFile = "big-trades.state.json";
var saved = File.Exists(StateFile) ? JsonValue.Parse(File.ReadAllText(StateFile)).Deserialize<Saved>() : null;
var objects = saved?.Items.ToDictionary(item => item.Id) ?? new Dictionary<string, Item<BigTradesData>>();

await using var stream = new FathomChartsStream(new StreamOptions
{
    Url = "wss://stream.fathomcharts.com/v1",
    ApiKey = Environment.GetEnvironmentVariable("FATHOM_CHARTS_API_KEY"),
});

var sub = stream.Subscribe<BigTradesData>(new SubscribeOptions
{
    Instrument = "NQ.front",
    Indicator = IndicatorIds.BigTrades,
    Params = new BigTradesParams { Minimum = 30 },
    Mode = Mode.Confirmed,
    From = saved is null ? From.Live : From.Cursor(saved.Cursor, saved.Engine),
});

await foreach (var e in sub)
{
    switch (e)
    {
        case Snapshot<BigTradesData> snapshot:
            objects = snapshot.Items.ToDictionary(item => item.Id);
            break;
        case Upsert<BigTradesData> upsert:
            objects[upsert.Id] = new Item<BigTradesData>(upsert.Id, upsert.Final, upsert.Ts, upsert.Data);
            break;
        case Remove remove:
            objects.Remove(remove.Id);
            break;
        case Reset:
            objects.Clear();
            break;
    }
    // Saved once an event that carries a cursor is applied: the cursor, the engine and the state then belong together.
    if (e is Snapshot<BigTradesData> or Upsert<BigTradesData> or Remove && sub.Cursor is { } cursor && sub.Engine is { } engine)
        File.WriteAllText(StateFile, JsonValue.FromObject(new Saved { Cursor = cursor, Engine = engine, Items = objects.Values.ToList() }).ToString());
}

class Saved
{
    public string Cursor { get; set; } = "";
    public string Engine { get; set; } = "";
    public List<Item<BigTradesData>> Items { get; set; } = new();
}
src/main.rs
use std::collections::HashMap;
use std::path::Path;

use fathom_charts::{FathomChartsStream, Item, Mode, StartFrom, StreamEvent, SubscribeOptions};
use futures::StreamExt;
use serde::{Deserialize, Serialize};
use serde_json::json;

mod fathom_charts_types;
use fathom_charts_types::BigTradesData;

// A file here; in production, the storage of your state (a database…).
const STATE_FILE: &str = "big-trades.state.json";

#[derive(Serialize, Deserialize)]
struct Saved {
    cursor: String,
    engine: String,
    items: Vec<Item<BigTradesData>>,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let saved: Option<Saved> =
        if Path::new(STATE_FILE).exists() { Some(serde_json::from_str(&std::fs::read_to_string(STATE_FILE)?)?) } else { None };
    let (from, mut objects) = match saved {
        Some(saved) => (
            StartFrom::Cursor { cursor: saved.cursor, engine: Some(saved.engine) },
            saved.items.into_iter().map(|item| (item.id.clone(), item)).collect(),
        ),
        None => (StartFrom::Live, HashMap::new()),
    };

    let stream = FathomChartsStream::builder("wss://stream.fathomcharts.com/v1")
        .api_key(std::env::var("FATHOM_CHARTS_API_KEY").map_err(|_| "FATHOM_CHARTS_API_KEY is not set")?)
        .build()?;

    let mut sub = stream.subscribe::<BigTradesData>(
        SubscribeOptions::new("NQ.front", "big-trades")
            .params(json!({ "minimum": 30 }))
            .mode(Mode::Confirmed)
            .from(from),
    )?;

    while let Some(event) = sub.next().await {
        let carries_cursor = match event? {
            StreamEvent::Snapshot(snapshot) => {
                objects = snapshot.items.into_iter().map(|item| (item.id.clone(), item)).collect();
                true
            }
            StreamEvent::Upsert(upsert) => {
                objects.insert(upsert.id.clone(), Item { id: upsert.id, is_final: upsert.is_final, ts: upsert.ts, data: upsert.data });
                true
            }
            StreamEvent::Remove(remove) => {
                objects.remove(&remove.id);
                true
            }
            StreamEvent::Reset(_) => {
                objects.clear();
                false
            }
            _ => false,
        };
        // Saved once an event that carries a cursor is applied: the cursor, the engine and the state then belong together.
        if let (true, Some(cursor), Some(engine)) = (carries_cursor, sub.cursor(), sub.engine()) {
            let items = objects.values().cloned().collect();
            std::fs::write(STATE_FILE, serde_json::to_string(&Saved { cursor, engine, items })?)?;
        }
    }
    Ok(())
}

What follows depends on how far back the cursor is:

  • Within the stream’s memory (about the last 15 minutes of updates): you receive subscribed, the upsert and remove events after your cursor, then a status. A resume sends no snapshot: the events apply to the state you saved, which is why it is saved with the cursor. This is free.
  • Beyond that memory, the resume is replayed from history when your rights cover the cursor’s UTC day: the Historical plan, or the last 7 days with the Live plan or the Sandbox rights. You receive the same events, without a snapshot, until live data is reached. The part replayed from history is charged like a from a time: the trades after the cursor’s trade, for the part before midnight UTC; the current UTC day is free, and so are the last 7 days with the Live plan. The subscription can then end with QUOTA_EXCEEDED (your compute budget does not cover it) or NOT_COVERED (the data is not available).
  • Without those rights (a cursor older than your plan’s depth), or with a cursor beyond the current position of the stream, you receive subscribed, then a reset with reason cursor_expired, a new snapshot and a status: start over from that snapshot.
  • The computation changed since the cursor was saved (its engine is no longer the current one): subscribed with the new engine, a reset with reason engine_change, a new snapshot and a status.

See Cursors and resuming. The examples save the cursor, the engine and the state after a snapshot, upsert or remove: after subscribed or reset, the engine may already be the new one while the cursor is still the old one, and saving that pair would resume the old state under the new computation. The heartbeat repeats the last cursor sent: it moves the subscription’s cursor forward only after a replay from history, to the end of the replay. On a quiet stream, the cursor stays on the last one received, and resuming from it loses nothing: the resume replays what followed it.

Rate limit and retries

Over REST, the SDK retries for you, up to 3 times by default:

  • a 429 RATE_LIMITED, after the delay of the Retry-After header (in seconds or as an HTTP date; 60 seconds at most), or, without that header, after 1, 2, then 4 seconds;
  • a 503 with a Retry-After header (not processed), after that delay;
  • a read (usage, status, instruments, catalog) that failed without a response or with a 502, during an update of the service for example, after 0.5, 1, then 2 seconds. A query page or an export is not retried: it may have been computed and charged.

429 QUOTA_EXCEEDED (monthly budget used up) is never retried: it is thrown at once. Cancelling a call ends the wait right away.

An export read with the SDK (exportNdjson()export_ndjson()ExportNdjsonAsync()export_ndjson()) resumes by itself after an interruption, after the last line received, as long as its first request succeeded: see Exports.

Errors

Every error an SDK throws, or ends a loop with, carries a stable code: an API code (see Errors), one of the SDK’s own (below), or HTTP_<status> (HTTP_502, for example) for an HTTP error response without a problem+json document. It also carries, when known, the HTTP status, the WebSocket close code, the Retry-After delay and the full problem+json document (with errors when the API lists invalid fields), and the error it stems from. Its message, over REST, is the detail of the response followed by the invalid fields it does not already name (<detail>: <path> <message>; …). Over the WebSocket, it is the text of the server’s error message: the fields are then written params.minimum, where REST writes the JSON Pointer /params/minimum.

codeCause
CONFIGURATIONInvalid options, before anything is sent: a missing or empty API key, a key with spaces or control characters around it, an API key and a stream token together, a URL that is not ws:///wss:// (stream) or http:///https:// (REST), a stream token function that fails with an error the SDK does not retry (see Connection lifecycle) or does not return a token, a value JSON cannot carry (a bigint time in TypeScript), a from time of a subscription that is not a string (in TypeScript, also a from or to of a query that is not a string), a subscription message over the 64 KiB the server accepts (refused by subscribe, so that it does not close the connection of every subscription with 1009), an empty instrument or indicator of a subscription and a missing field of a query (C#, Rust); data that does not fit the requested type (C#, Rust); or a feature missing from the platform.
CLOSEDA subscription on a stream that was closed.
KEY_REVOKEDThe connection was closed (4003) because the key was revoked or expired.
ENTITLEMENTS_CHANGEDThe connection was closed (4003) because your rights no longer cover it (offer ended, account suspended, subscription quota exceeded).
TOO_MANY_CONNECTIONSYour plan’s connection limit was still reached (4029) after the retry period. The message says so and how long the SDK retried: close another connection, then subscribe again.
PROTOCOL_ERROR, BINARY_NOT_SUPPORTED, INVALID_UTF8, MESSAGE_TOO_BIGThe server refused a message sent by the client (close codes 1002, 1003, 1007, 1009): the close reason is the code.
ABORTEDA REST call cancelled (TypeScript: its AbortSignal; C#: its CancellationToken; Rust: the timeout of its HTTP client), or, in C#, a subscription loop cancelled by its CancellationToken. In Python, cancelling the task raises CancelledError, as asyncio requires, and ABORTED is not in its ERROR_CODES.
NETWORK_ERRORThe API could not be reached, or the connection was lost during a response (DNS, refused or reset connection, TLS).
UPSTREAM_ERRORAlso an API code. From the SDK: a success response that is not valid JSON, or an export whose decompression fails; in C#, JSON whose values do not have the type this SDK version expects (a number where it expects text, for example). A new value of a known field is not an error (see Events).
HTTP_<status>An HTTP error response without a problem+json document, or a WebSocket opening refused with a 4xx (other than 429).

Cursors

compareCursors(a, b)compare_cursors(a, b)Cursors.Compare(a, b)compare_cursors(a, b) compares two cursors <utcDay>.<rank>.<k> number by number (negative, zero or positive; an Ordering in Rust). The three numbers are unsigned 32-bit integers: a malformed cursor (numbers with leading zeros or above 4294967295, a missing field…) throws INVALID_PARAMETERS. See Cursors.

Which cursor is for what

  • The cursor of an event (snapshot, upsert, remove) and sub.cursorsub.cursorsub.Cursorsub.cursor(): a position in the stream, <utcDay>.<rank>.<k>, the same live and in history. Save it with the engine to resume (from a cursor), compare it to skip what you already applied, or give it as untilCursor to stop a history query there. Ranks count the trades of one instrument: never compare the cursors of two instruments.
  • The next of a history page: a signed string, valid only for your account and the same query. Send it back as is, in the cursor field of the request for the next page; it is not a stream cursor, and rest.pages()rest.pages()rest.PagesAsync()rest.pages() and rest.history()rest.history()rest.HistoryAsync()rest.history() follow it for you.
  • untilCursor (history): a stream cursor, from an item or a subscription, where a query stops, inclusive.
  • k = 4294967295 (the largest value): the position after every update of a trade. You meet it in three cases: the cursor of a snapshot when nothing has been published since the start of the computation period; the cursor of the snapshot of a from a time subscription when nothing was published between midnight UTC and that time, <previous utcDay>.<rank>.4294967295, the position after the last trade of the previous UTC day (even if updates were published earlier in the session); and the subscription’s cursor after a replay from history, until a new update follows. These are cursors like any other: save them and resume from them the same way.