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
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):
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 ;
use StreamExt;
use json;
use BigTradesData;
async
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
let stream = builder
.stream_token
.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 ;
use StreamExt;
use json;
let rest = new?;
let query = new.params;
let mut history = Boxpin;
while let Some = history.next.await
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 ;
use AsyncWriteExt;
let query = new.params;
let mut file = create.await?;
let mut lines = Boxpin;
while let Some = lines.next.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::Timereplay 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, withoutResetnor snapshot (the historical part is charged like theFrom::Time). Otherwise the subscription receivesReset(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 atmax_buffered. While paused, the SDK sendspingmessages so that the server keeps the connection.max_buffered(default 4 ×high_water_mark): a socket given toweb_socketthat cannot be paused (Socket::pausablefalse) stops being read there: the SDK closes the connection (close code 4000,CloseCode::CLIENT_RECONNECT, reasonclient buffer full; the state goesReconnectingat 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 ofhigh_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 sendshbevery 5 s), the SDK closes the connection (close code 4000, reasonheartbeat timeout) and reopens it. It checks every third of the delay: a silence is detected betweenheartbeat_timeoutand 4/3 of it.web_socket(f): opens the connections,f(url, headers) -> impl Future<Output = Result<Socket, Error>>(headersholdsAuthorizationwith an API key,Nonewith a stream token); aSockethasincoming(a stream ofFrame::Text/Frame::Close { code, reason }),outgoing(a sink ofFrame) andpausable. DefaultSocket::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 leastquota_retry(the attempt in progress at its end finishes first), then every subscription ends withTOO_MANY_CONNECTIONS; meanwhile each refused connection opens then closes, so the state alternates betweenOpenandReconnecting. A4008is resumed at once, unless the connection closed again before anysubscribed: then with the backoff.random: source of the reconnection jitter, in [0, 1) (for tests).on_noticereceives the server notices (Reconnect;Maintenancewithid,effective_at,ends_at,message;MaintenanceCancelledwithid), also given to every subscription asNoticeevents;stream.maintenance()lists the maintenance windows announced and not over;on_state_changethe connection state (Idle,Connecting,Open,Reconnecting,Closed), also readable asstream.connection_state();stream.last_close()(aConnectionClose { code, reason }) tells how the connection last closed, set beforeon_state_changeis called.
A Subscription<T> is a futures::Stream of Result<StreamEvent<T>, Error>, with:
id(): itssubon 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 anhbthat 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 latestSubscribed;engine(): engine build from the latestSubscribed; save it withcursor()and resume a later process withFrom::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, bothapi_keyandstream_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, orOther(code)for a code this version does not know.ErrorCodeis#[non_exhaustive](amatchneeds a_arm); it compares with a string (e.code() == "FORBIDDEN"), andcode().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,Nonewhen the answer is not one;problem_errors(): its invalid fields, aVec(empty otherwise);source()(thestd::error::Errormethod: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.