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).
| Language | Package | Runs on | Reference |
|---|---|---|---|
| TypeScript | @fathom-charts/sdk (npm) | Node 22.15+, browsers | TypeScript SDK |
| Python | fathom-charts (PyPI) | Python 3.11+, asyncio | Python 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 |
| Rust | fathom-charts (crates.io) | Rust 1.88+, Tokio | Rust SDK |
Install
npm install @fathom-charts/sdk@0.6.0 wspip install fathom-charts==0.6.0dotnet add package FathomCharts --version 0.6.0cargo add fathom-charts@0.6.0
cargo add tokio --features full
cargo add futures serde serde_json --features serde/deriveIn 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.
npx -p @fathom-charts/sdk@0.6.0 fathom-charts-types https://api.fathomcharts.com/v1/indicators src/fathom-charts-types.tsfathom-charts-types https://api.fathomcharts.com/v1/indicators fathom_charts_types.pydotnet dnx FathomCharts.Types@0.6.0 https://api.fathomcharts.com/v1/indicators FathomChartsTypes.cscargo install fathom-charts@0.6.0 --features cli --locked
fathom-charts-types https://api.fathomcharts.com/v1/indicators src/fathom_charts_types.rsA 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).
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);
}
}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())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;
}
}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).
| Event | Fields | When |
|---|---|---|
subscribed | topic, instrument, tickSizeNanos, engine | The subscription is accepted. Arrives again after every reconnection, and before a reset with reason roll, entitlement_changed or engine_change. |
snapshot | cursor, items (each id, final, ts, data) | The starting state. Replace your whole local state with items. |
upsert | cursor, id, final, ts, data | Object id is created or entirely replaced. |
remove | cursor, id, final, ts | Object id is deleted. |
status | state, lagMs | The stream status (see Stream status). Arrives again after every reconnection. |
reset | reason | Your local state is no longer valid: discard it, a snapshot follows. |
notice | kind, 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. |
retrying | code, message, delayMs | A 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, astatuswith statewarmingwhen the stream is still being prepared,snapshot, thenstatus(live, for example); - a subscription that starts in the past (
fromatime):subscribed, awarmingstatuswhen the stream is still being prepared, thesnapshotat that time, theupsertandremoveevents replayed since then, thenstatusliveonce the replay has caught up with live data, and live events after it; - a resume:
subscribed, the missedupsertandremoveevents, thenstatus, without a snapshot; - a change of computation or contract:
subscribed,reset,snapshot, thenstatus.
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==, andToString()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 itsitems;upsert: create objectid, or replace it entirely (anupsertcarries the whole object, never a difference);remove: delete objectid;reset: clear everything; asnapshotfollows.
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:
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;
}
}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())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;
}
}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 withblock; closing it; or a servererroron it that is not retried), the SDK closes the connection (code1000, reasonidle) and the connection state becomesidle. 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 fromidle),open,reconnecting(from the moment a connection drops, whoever closed it, until a new one opens) orclosed(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 (4029TOO_MANY_CONNECTIONSwhen every connection of your plan is in use, for example),1005for a close frame without a code,1006when the connection was lost without one, or the SDK’s own close (4000heartbeat timeoutorclient buffer fullbefore it reconnects;1000idlewhen the last subscription closed,client closedwhen you closed the stream while the connection was still open,failedafter a final error). Closing the stream after its last loop has ended leaves1000idle: the connection was already closed. It is set before the state changes: when the state becomesreconnecting, 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 code | What the SDK does |
|---|---|
4001 | Ends 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. |
4003 | Ends 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, 1009 | Ends 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. |
4029 | Retries, 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. |
4008 | Reconnects 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, 1013 | Reconnects 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 message | Reconnects 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:
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));
}
}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())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();
}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, theupsertandremoveevents after your cursor, then astatus. 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
fromatime: 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 withQUOTA_EXCEEDED(your compute budget does not cover it) orNOT_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 aresetwith reasoncursor_expired, a new snapshot and astatus: start over from that snapshot. - The computation changed since the cursor was saved (its engine is no longer the current one):
subscribedwith the new engine, aresetwith reasonengine_change, a new snapshot and astatus.
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 theRetry-Afterheader (in seconds or as an HTTP date; 60 seconds at most), or, without that header, after 1, 2, then 4 seconds; - a
503with aRetry-Afterheader (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.
code | Cause |
|---|---|
CONFIGURATION | Invalid 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. |
CLOSED | A subscription on a stream that was closed. |
KEY_REVOKED | The connection was closed (4003) because the key was revoked or expired. |
ENTITLEMENTS_CHANGED | The connection was closed (4003) because your rights no longer cover it (offer ended, account suspended, subscription quota exceeded). |
TOO_MANY_CONNECTIONS | Your 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_BIG | The server refused a message sent by the client (close codes 1002, 1003, 1007, 1009): the close reason is the code. |
ABORTED | A 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_ERROR | The API could not be reached, or the connection was lost during a response (DNS, refused or reset connection, TLS). |
UPSTREAM_ERROR | Also 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) andsub.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 (fromacursor), compare it to skip what you already applied, or give it asuntilCursorto stop a history query there. Ranks count the trades of one instrument: never compare the cursors of two instruments. - The
nextof a history page: a signed string, valid only for your account and the same query. Send it back as is, in thecursorfield of the request for the next page; it is not a stream cursor, andrest.pages()rest.pages()rest.PagesAsync()rest.pages()andrest.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 afromatimesubscription 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.