Skip to main content

Crate fathom_charts

Crate fathom_charts 

Source
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).
CatalogField
One field of the data of an indicator object.
CatalogIndicator
CatalogObject
One kind of object an indicator publishes.
CatalogParam
One parameter of an indicator in the catalog.
CloseCode
WebSocket close codes of the gateway, and the one the SDK closes with before it reconnects (CLIENT_RECONNECT).
ConnectionClose
How the connection last closed (FathomChartsStream::last_close): the server’s close frame (4029 TOO_MANY_CONNECTIONS when every connection of the plan is in use…), 1006 when it was lost without one, or the SDK’s own close (4000 before it reconnects, 1000 idle).
EngineStatus
Error
Error raised by the SDK: a stable code (ErrorCode), the HTTP status or WebSocket close code when known.
Estimate
ExportOptions
ExportResume
Resumption of a cut export: X-Export-Token of its first response and cursor of the last complete line received.
ExportStream
One export response.
FathomChartsRest
REST helpers of the public API, authenticated by API key. A cheap handle: clones share the HTTP client.
FathomChartsStream
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).
InstrumentStatus
An instrument in the service status.
Item
One object of a snapshot: the latest state of an indicator object.
Limits
MaintenanceWindow
A maintenance window announced and not cancelled: the service may pause between starts_at and ends_at (Unix ns).
Mutation
One mutation of a historical range: as the upsert and remove messages of a subscription, with their cursor.
Notice
A notice of the gateway (times: Unix ns, decimal strings). See NoticeKind.
Page
PageQuery
A range of an indicator’s history, read page by page (page, pages, history, estimate).
PageSnapshot
State at from (snapshot: true): the objects then, as the snapshot of a subscription, and the cursor it covers.
ProblemFieldError
One invalid field of a request: JSON Pointer from the root of the body, and what is wrong with it.
RangeQuery
A range of an indicator’s history (exports).
Reconnect
Reconnection delays.
Remove
Reset
RestBuilder
Options of a FathomChartsRest.
Retrying
A transient error (code, message) ended the subscription on the server: the SDK subscribes it again in delay_ms.
ServiceStatus
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 to StreamBuilder::web_socket.
Status
StreamBuilder
Options of a FathomChartsStream: FathomChartsStream::builder(url), then exactly one of api_key and stream_token.
StreamToken
Single-use stream token (POST /v1/stream-tokens).
SubscribeOptions
One subscription as requested; new fills 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 Stream of events (while let Some(event) = sub.next().await). A failure is yielded once, then the stream ends. Dropping it, or close, unsubscribes.
Upsert
Usage
Usage of the account this period (GET /v1/usage).
UsageCounters
UsageRemaining

Enums§

ConnectionState
ErrorCode
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, engine is the engine build that cursor comes from (subscribed.engine): under another build the subscription restarts from a snapshot after reset (engine_change) instead of resuming state computed differently.
HistoryItem
An element of FathomChartsRest::history: with snapshot: true, the snapshot comes first, then the mutations.
Mode
Confirmed: final mutations only. Live (default): every version published in real time.
MutationKind
NoticeKind
Reconnect: the gateway restarts (deployment) and closes the connection (1012) within seconds; Maintenance: a window (id, effective_at to ends_at, message) during which the service may pause; MaintenanceCancelled: the window id is cancelled.
ResetReason
Why a subscription starts over from a snapshot (reset events).
SourceState
State of the source of an instrument (status events, GET /v1/instruments).
StreamEvent
An event of a subscription. Serialized as on the wire, with its kind in type ({"type":"upsert","cursor":…}).

Constants§

ERROR_CODES
Every code of ErrorCode but HTTP_<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_token function: any error, sent and shared between threads.
ByteStream
A stream of bytes read at the consumer’s pace.
StartFrom
From under a name that does not hide std::convert::From once imported: use fathom_charts::StartFrom;, then StartFrom::Live, StartFrom::Cursor { .. } or StartFrom::Time(..).