Rust SDK

fathom-charts handles authentication, the initial snapshot, resuming after a disconnect, duplicates, history pagination, exports and rate-limit retries for you, on Tokio. This page describes every option and method; the behaviour the four SDKs share is in SDKs.

Install

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

• Rust 1.88 or later, on Tokio: a runtime with its time and I/O drivers, as #[tokio::main] gives. Building a stream outside a runtime returns CONFIGURATION.
• TLS is rustls: nothing native to install.
• Subscriptions and paginated results are futures::Streams: read them with StreamExt::next.

Indicator types

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

The command takes the catalog’s URL or a file saved from GET /v1/indicators; declare the file as a module (mod fathom_charts_types;). It needs serde (with derive) and serde_json. Per indicator: <Name>Params and <Name>Data (big-trades → BigTradesParams, BigTradesData), with the catalog’s descriptions as doc comments; strings with a fixed set of values become enums, optional fields Option<_>, and a tuple with optional elements, such as a footprint level [price, bid, ask, unknown?], a Vec<i64> whose shape its doc comment gives. INDICATOR_IDS lists the ids, and each indicator implements the Indicator trait (ID, Params, Data). Generate the file again when the catalog changes.

Real time: FathomChartsStream

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")?)
        .on_state_change(|state| println!("connection {state:?}"))
        .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.cursor, upsert.data.side, upsert.data.volume);
        }
    }
    Ok(())
}

Options

Methods of FathomChartsStream::builder(url), durations as Duration, then build()?:

stream.close() closes every subscription and the connection. stream.connection_state() is Idle, Connecting, Open, Reconnecting or Closed; stream.maintenance() lists the maintenance windows announced on the connection and not over, by start.

subscribe()

stream.subscribe::<T>(options)? opens a subscription and returns a Subscription<T>. SubscribeOptions::new(instrument, indicator) holds the fields of the subscribe message, with .params(json!({…})) (or serde_json::to_value of a generated <Name>Params), .mode(Mode::Confirmed) (Mode::Live by default) and .from(…) (From::Live by default, From::Cursor { cursor, engine } or From::Time(time)). The SDK picks the sub name itself. T is the indicator’s data type (BigTradesData…), serde_json::Value by default.

A Subscription<T> is a futures::Stream of Result<StreamEvent<T>, Error>. StreamEvent is Subscribed, Snapshot, Upsert, Remove, Status, Reset or Notice; their fields are those of Events, in snake case (tick_size_nanos, lag_ms; is_final for final). An error on the subscription is yielded once as an Err, then the stream ends. Data that does not fit T is yielded as an UPSTREAM_ERROR, and the subscription ends.

Subscription

Dropping the subscription closes it. Reconnection, resuming and close codes: see Connection lifecycle; to resume after your process restarts, see Resume after a restart.

History: FathomChartsRest

use fathom_charts::FathomChartsRest;

let rest = FathomChartsRest::new("https://api.fathomcharts.com", std::env::var("FATHOM_CHARTS_API_KEY")?)?;

FathomChartsRest::builder(base_url) sets the options:

Methods

Queries are PageQuery::new(instrument, indicator, from, to) and, for exports, RangeQuery::new(…), with .params(…), .mode(…) and the other fields of the History page (limit, cursor, until_cursor, snapshot), serialized as the API expects.

Cancellation is Rust’s: dropping the future of a call, or a 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. Its codes are listed in Errors: code() is an ErrorCode (InvalidParameters, Forbidden, Configuration, Http(status)…), code().as_str() gives it as on the wire, and ERROR_CODES lists them; CloseCode lists the WebSocket close codes.

Cursors

use fathom_charts::compare_cursors;

compare_cursors("20720.111416.0", "20720.111417.0")?; // Ordering::Less