fathom-charts 0.6.1

Fathom Charts client: real-time order-flow indicator streams (WebSocket) and history (REST), for Rust (tokio).
Documentation

fathom-charts

Rust client for Fathom Charts: real-time order-flow indicator streams (WebSocket) and history (REST), on Tokio.

The SDK handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination and rate-limit retries.

Documentation: fathomcharts.com/docs/sdk/rust

Install

cargo add fathom-charts
cargo add tokio --features full
cargo add futures serde serde_json --features serde/derive

The SDK runs on Tokio (a runtime with its time and I/O drivers, as #[tokio::main] gives). TLS is rustls: no OpenSSL, but a C compiler is needed (MSVC Build Tools on Windows, cc on Linux). Rust 1.88 or later.

Generate the types of each indicator's parameters and data from the catalog (GET /v1/indicators, no authentication), with the command of the same version as the SDK (a release build, about 1 to 2 minutes):

cargo install fathom-charts@0.6.0 --features cli --locked
fathom-charts-types https://api.fathomcharts.com/v1/indicators src/fathom_charts_types.rs

The generated file needs serde (with derive); its header says when it also needs serde_json. The command is silent when it succeeds (exit code 0); on failure it prints one line (fathom-charts-types: …) and exits with 1; with wrong arguments it prints its usage and exits with 2. Per indicator: <Name>Params and <Name>Data (big-trades → BigTradesParams, BigTradesData), the catalog's descriptions as doc comments; strings of an enum become Rust enums with an Other(String) variant for a value the catalog does not list yet (read as it is, never an error; printed with {} as on the wire: sell; as_str()), optional fields Option<_>, objects of several kinds an untagged enum with one variant per kind (EffortZonesData::Bar(…)), and tuples with optional elements ([price, bid, ask, unknown?]) lists (Vec<i64>, their shape in the doc comment). Each indicator implements the Indicator trait (ID, Params: Serialize + DeserializeOwned + Default…, Data: DeserializeOwned…), so generic code can use I::Params::default() and subscribe::<I::Data>.

Real time

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),
    )?;

    while let Some(event) = big_trades.next().await {
        if let StreamEvent::Upsert(upsert) = event? {
            println!("{} {} {}", upsert.data.side, upsert.data.volume, upsert.data.price);
        }
    }
    Ok(())
}

T of subscribe::<T> (and of page, pages, history) is the type of the objects' data: a generated <Name>Data, or serde_json::Value for untyped data, named explicitly (subscribe::<serde_json::Value>(…)). Data that does not fit T ends the subscription with CONFIGURATION ("The data of big-trades does not fit FootprintData: missing field close").

The events are StreamEvent::Subscribed, Snapshot, Upsert, Remove, Status, Reset, Notice and Retrying; StreamEvent is #[non_exhaustive] (a match needs a _ arm). An empty instrument or indicator, or a subscribe message over 65,536 bytes (UTF-8), is refused by subscribe() with CONFIGURATION, nothing sent. Heartbeats and pongs are handled by the SDK; notices (a restart, a maintenance window announced or cancelled) reach every subscription and on_notice; an error on the subscription with a transient code (UPSTREAM_ERROR, CAPACITY, INTERNAL, SOURCE_DOWN) gives Retrying (code, message, delay_ms) and the SDK subscribes again from the last cursor received, after a backoff (0.5 s, doubling up to 30 s); any other error is yielded once as an Err(fathom_charts::Error), then the stream ends. Dropping the subscription (or close()) unsubscribes; the connection closes when no subscription is left. See Real time.

An application distributed to end users must not hold the API key: give it stream_token instead of api_key, a function returning a fresh single-use token that your backend gets from POST /v1/stream-tokens (FathomChartsRest::stream_token), called on every connection:

// Asks your backend for a token: its route calls `FathomChartsRest::stream_token` with your API key.
async fn fetch_token_from_my_backend() -> Result<String, reqwest::Error> {
    reqwest::get("https://my-app.example/stream-token").await?.error_for_status()?.text().await
}

let stream = FathomChartsStream::builder("wss://stream.fathomcharts.com/v1")
    .stream_token(|| async { Ok(fetch_token_from_my_backend().await?) })
    .build()?;

The function returns Result<String, fathom_charts::BoxError>. When it fails with a network failure (an I/O error, a reqwest connection, request or timeout error raised before any answer, an elapsed tokio::time::timeout) or a fathom_charts::Error NetworkError, RateLimited, Capacity, HTTP_429 or with a status of 500 or more, the SDK calls it again with the reconnection backoff; QuotaExceeded (status 429) is not retried. Any other error (a bug in the function, a reqwest status error from error_for_status included) ends every subscription: a fathom_charts::Error as it is, another error as CONFIGURATION ("stream_token failed: …", the original as source()). An empty token, or one with spaces or control characters around it, ends them with CONFIGURATION too.

History

use fathom_charts::{FathomChartsRest, HistoryItem, PageQuery};
use futures::StreamExt;
use serde_json::json;

let rest = FathomChartsRest::new(
    "https://api.fathomcharts.com",
    std::env::var("FATHOM_CHARTS_API_KEY").map_err(|_| "FATHOM_CHARTS_API_KEY is not set")?,
)?;

let query = PageQuery::new("NQZ6", "big-trades", "1790256600000000000", "1790258100000000000").params(json!({ "minimum": 30 }));
let mut history = Box::pin(rest.history::<BigTradesData>(query));
while let Some(item) = history.next().await {
    if let HistoryItem::Mutation(m) = item? {
        if let (true, Some(data)) = (m.is_final, m.data) {
            println!("{} {} {}", m.cursor, data.side, data.volume);
        }
    }
}

page, pages (a stream of pages), estimate (a PageQuery: PageQuery::from(range_query) to estimate an export), export, usage, instruments, status and indicators complete it; a query with an empty instrument, indicator, from or to fails with CONFIGURATION before anything is sent. The streams of pages, history and export_ndjson must be pinned before .next() (Box::pin(…) or futures::pin_mut!). On error, the SDK returns a fathom_charts::Error carrying the error code. See History.

Export to a file

export_ndjson streams a range as decompressed NDJSON, in chunks of whole lines (one mutation per line), and resumes by itself after a cut (connection lost, deployment of the service, 5xx answer) from the last line received: the chunks concatenate to exactly the lines of an uninterrupted export, charged once. The first request is never sent again: when it fails, its error is yielded.

use fathom_charts::{ExportOptions, RangeQuery};
use tokio::io::AsyncWriteExt;

let query = RangeQuery::new("NQZ6", "footprint", "1790208000000000000", "1790294400000000000").params(json!({ "timeframe": 60 }));
let mut file = tokio::fs::File::create("footprint.ndjson").await?;
let mut lines = Box::pin(rest.export_ndjson(query, ExportOptions::default()));
while let Some(chunk) = lines.next().await {
    file.write_all(&chunk?).await?;
}
file.flush().await?;

ExportOptions: max_resumes (5 consecutive resumptions without a new line), resume_delay (1 s, doubled up to 30 s). export gives the raw zstd file of one response instead, with its resume token.

Connection, resume and flow control

FathomChartsStream multiplexes its subscriptions on one connection and reopens it after a cut (backoff with jitter), resuming each subscription after its last cursor received, with the engine build its state comes from; events already received are never delivered twice. During an update of the service the stream pauses and resumes by itself; when the computation of an indicator changed, the subscription receives Reset (EngineChange), Subscribed and a new snapshot. See Updates and maintenance.

  • A resume within the server's memory of recent messages continues where it stopped. An older one (a long cut, or a long From::Time replay interrupted) is caught up from history when your offer includes it and its depth reaches the cursor's UTC day: the rest of the replay follows, then real time, without Reset nor snapshot (the historical part is charged like the From::Time). Otherwise the subscription receives Reset (CursorExpired) followed by a fresh snapshot.
  • high_water_mark (default 10 000 queued events): above it, the SDK stops reading the socket (TCP backpressure up to the server); the server then keeps only the latest version of each object in progress. With a socket that cannot be paused, the SDK itself replaces a queued provisional version by the newer one, and closes the connection at max_buffered. While paused, the SDK sends ping messages so that the server keeps the connection.
  • max_buffered (default 4 × high_water_mark): a socket given to web_socket that cannot be paused (Socket::pausable false) stops being read there: the SDK closes the connection (close code 4000, CloseCode::CLIENT_RECONNECT, reason client buffer full; the state goes Reconnecting at once and stays so until the connection is open again) and reopens it from the last queued cursor once the events waiting fall to half of high_water_mark. A subscription added meanwhile waits for that reopening. Nothing queued is lost, and the resume rules above apply.
  • heartbeat_timeout (default 15 s): without any message for this long (the server sends hb every 5 s), the SDK closes the connection (close code 4000, reason heartbeat timeout) and reopens it. It checks every third of the delay: a silence is detected between heartbeat_timeout and 4/3 of it.
  • web_socket(f): opens the connections, f(url, headers) -> impl Future<Output = Result<Socket, Error>> (headers holds Authorization with an API key, None with a stream token); a Socket has incoming (a stream of Frame::Text / Frame::Close { code, reason }), outgoing (a sink of Frame) and pausable. Default Socket::connect.
  • A handshake refused with HTTP 4xx (but 429), such as a wrong path, ends every subscription with HTTP_<status>; 5xx and 429 are retried.
  • reconnect(Reconnect { … }): initial_delay (250 ms), max_delay (30 s), quota_retry (how long close code 4029 is retried, 120 s), quota_delay (5 s). A 4029 is retried for at least quota_retry (the attempt in progress at its end finishes first), then every subscription ends with TOO_MANY_CONNECTIONS; meanwhile each refused connection opens then closes, so the state alternates between Open and Reconnecting. A 4008 is resumed at once, unless the connection closed again before any subscribed: then with the backoff.
  • random: source of the reconnection jitter, in [0, 1) (for tests).
  • on_notice receives the server notices (Reconnect; Maintenance with id, effective_at, ends_at, message; MaintenanceCancelled with id), also given to every subscription as Notice events; stream.maintenance() lists the maintenance windows announced and not over; on_state_change the connection state (Idle, Connecting, Open, Reconnecting, Closed), also readable as stream.connection_state(); stream.last_close() (a ConnectionClose { code, reason }) tells how the connection last closed, set before on_state_change is called.

A Subscription<T> is a futures::Stream of Result<StreamEvent<T>, Error>, with:

  • id(): its sub on the connection (s1, s2…), as in the protocol messages;
  • request(): the subscription as requested, defaults filled in (params: {}, Mode::Live, From::Live);
  • cursor(): cursor of the last event handed to your loop, the resume point; when no event is waiting to be read, it also moves to the cursor of an hb that is later (after a replay from history, for example). On a stream with no update, it stays on the last cursor received: resuming from it loses nothing;
  • topic(): topic key from the latest Subscribed;
  • engine(): engine build from the latest Subscribed; save it with cursor() and resume a later process with From::Cursor { cursor, engine };
  • close(): unsubscribes (as dropping it does).

CloseCode lists the gateway's WebSocket close codes, and CLIENT_RECONNECT (4000), the SDK's own; compare_cursors(a, b) orders two cursors (<utcDay>.<rank>.<k>, unsigned 32-bit integers; InvalidParameters otherwise).

Cancellation is Rust's: dropping a subscription unsubscribes, and dropping the future of a REST call, or the stream of pages, history or export_ndjson, stops it, including while it waits to retry.

Errors

Every error the SDK returns, or ends a stream with, is a fathom_charts::Error (ERROR_CODES lists the codes):

  • code(): a &ErrorCode, the API's code (InvalidParameters, Forbidden, QuotaExceeded…), or one of the SDK's own: Configuration (invalid options: missing or empty API key, a key with spaces around it, both api_key and stream_token, data that does not fit the type asked for…), Closed, KeyRevoked, EntitlementsChanged, TooManyConnections, ProtocolError, BinaryNotSupported, InvalidUtf8, MessageTooBig, Aborted (a REST call stopped by the timeout of its HTTP client), NetworkError (the API could not be reached, or the connection was lost during an answer), Http(status) (HTTP_<status>) for an HTTP error answer that is not a problem document, or Other(code) for a code this version does not know. ErrorCode is #[non_exhaustive] (a match needs a _ arm); it compares with a string (e.code() == "FORBIDDEN"), and code().as_str() gives it as on the wire;
  • message(); status(), close_code(), retry_after() when known;
  • problem(): the RFC 9457 problem document of an HTTP error, None when the answer is not one; problem_errors(): its invalid fields, a Vec (empty otherwise);
  • source() (the std::error::Error method: use std::error::Error as _;): the original error (of the HTTP client, of the WebSocket…), when there is one.

An error returned from main prints in its Debug form; print it with {} (eprintln!("{e}")), or match e.code(), for a readable message.

License

Proprietary (crates.io shows the licence as non-standard, as it is given by a LICENSE file rather than an SPDX identifier): you may use this package and include it in your own applications only to access the Fathom Charts service. See LICENSE.