Expand description
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: https://fathomcharts.com/docs/sdk/rust.
use fathom_charts::{FathomChartsStream, Mode, StreamEvent, SubscribeOptions};
use futures_util::StreamExt;
use serde_json::json;
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::<serde_json::Value>(
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);
}
}Cancellation is Rust’s: dropping a Subscription unsubscribes, dropping the future of a REST call or the stream of
pages, history or export_ndjson stops it (including while it waits to retry).
Structs§
- Catalog
- Indicator catalog (GET /v1/indicators).
- Catalog
Field - One field of the
dataof an indicator object. - Catalog
Indicator - Catalog
Object - One kind of object an indicator publishes.
- Catalog
Param - One parameter of an indicator in the catalog.
- Close
Code - WebSocket close codes of the gateway, and the one the SDK closes with before it reconnects (
CLIENT_RECONNECT). - Connection
Close - How the connection last closed (
FathomChartsStream::last_close): the server’s close frame (4029TOO_MANY_CONNECTIONSwhen every connection of the plan is in use…),1006when it was lost without one, or the SDK’s own close (4000before it reconnects,1000idle). - Engine
Status - Error
- Error raised by the SDK: a stable code (
ErrorCode), the HTTP status or WebSocket close code when known. - Estimate
- Export
Options - Export
Resume - Resumption of a cut export:
X-Export-Tokenof its first response and cursor of the last complete line received. - Export
Stream - One export response.
- Fathom
Charts Rest - REST helpers of the public API, authenticated by API key. A cheap handle: clones share the HTTP client.
- Fathom
Charts Stream - Multiplexed connection to the gateway: subscriptions share one socket, which reconnects with backoff and jitter and resumes every subscription from its last cursor; duplicates (cursor not after the last one) are dropped.
- Instrument
- One instrument served (GET /v1/instruments).
- Instrument
Status - An instrument in the service status.
- Item
- One object of a snapshot: the latest state of an indicator object.
- Limits
- Maintenance
Window - A maintenance window announced and not cancelled: the service may pause between
starts_atandends_at(Unix ns). - Mutation
- One mutation of a historical range: as the
upsertandremovemessages of a subscription, with their cursor. - Notice
- A notice of the gateway (times: Unix ns, decimal strings). See
NoticeKind. - Page
- Page
Query - A range of an indicator’s history, read page by page (
page,pages,history,estimate). - Page
Snapshot - State at
from(snapshot: true): the objects then, as thesnapshotof a subscription, and the cursor it covers. - Problem
Field Error - One invalid field of a request: JSON Pointer from the root of the body, and what is wrong with it.
- Range
Query - A range of an indicator’s history (exports).
- Reconnect
- Reconnection delays.
- Remove
- Reset
- Rest
Builder - Options of a
FathomChartsRest. - Retrying
- A transient error (
code,message) ended the subscription on the server: the SDK subscribes it again indelay_ms. - Service
Status - Source and service state (GET /v1/status).
- Snapshot
- The objects alive at
cursor. - Socket
- A WebSocket connection the stream reads and writes: the default one (
Socket::connect), or another one returned by the factory given toStreamBuilder::web_socket. - Status
- Stream
Builder - Options of a
FathomChartsStream:FathomChartsStream::builder(url), then exactly one ofapi_keyandstream_token. - Stream
Token - Single-use stream token (POST /v1/stream-tokens).
- Subscribe
Options - One subscription as requested;
newfills the defaults (params: {},mode: Live,from: Live). - Subscribed
- The subscription is served: its topic key and the contract it follows (an alias resolved, e.g.
NQ.front->NQZ6), with its price increment (1e-9 units, decimal string), and the fingerprint of the engine build computing it (engine, given back with a cursor to resume). - Subscription
- One indicator stream: a
Streamof events (while let Some(event) = sub.next().await). A failure is yielded once, then the stream ends. Dropping it, orclose, unsubscribes. - Upsert
- Usage
- Usage of the account this period (GET /v1/usage).
- Usage
Counters - Usage
Remaining
Enums§
- Connection
State - Error
Code - A code of
ERROR_CODES,HTTP_<status>for an HTTP error answer without a problem document, or a code this version of the SDK does not know yet (Other). - Frame
- One frame of a WebSocket connection: a text message, or the close frame (code and reason).
- From
- Start point: live edge, after a known cursor, or from a time (Unix ns, decimal string) through history into live. With a
cursor,
engineis the engine build that cursor comes from (subscribed.engine): under another build the subscription restarts from a snapshot afterreset(engine_change) instead of resuming state computed differently. - History
Item - An element of
FathomChartsRest::history: withsnapshot: true, the snapshot comes first, then the mutations. - Mode
Confirmed: final mutations only.Live(default): every version published in real time.- Mutation
Kind - Notice
Kind Reconnect: the gateway restarts (deployment) and closes the connection (1012) within seconds;Maintenance: a window (id,effective_attoends_at,message) during which the service may pause;MaintenanceCancelled: the windowidis cancelled.- Reset
Reason - Why a subscription starts over from a snapshot (
resetevents). - Source
State - State of the source of an instrument (
statusevents, GET /v1/instruments). - Stream
Event - An event of a subscription. Serialized as on the wire, with its kind in
type({"type":"upsert","cursor":…}).
Constants§
- ERROR_
CODES - Every code of
ErrorCodebutHTTP_<status>, as on the wire.
Functions§
- compare_
cursors - Orders two cursors
<utcDay>.<rank>.<k>(unsigned 32-bit decimal integers without leading zeros), part by part. Fails with INVALID_PARAMETERS when either is not a well-formed cursor.
Type Aliases§
- BoxError
- Error type of the
stream_tokenfunction: any error, sent and shared between threads. - Byte
Stream - A stream of bytes read at the consumer’s pace.
- Start
From Fromunder a name that does not hidestd::convert::Fromonce imported:use fathom_charts::StartFrom;, thenStartFrom::Live,StartFrom::Cursor { .. }orStartFrom::Time(..).