client.orderbook reads spot depth snapshots and maintains a stateful live book. It uses the
public transport, so no authentication is required. Realtime support is always compiled; the realtime Cargo feature is only an empty compatibility flag.
Levels are price/qty pairs, best-first (bids descending, asks ascending). Each snapshot carries book_seq, the backend sequence number used to detect gaps. available is true when the book is
current, so an empty side means no liquidity. When it is false the book is being built or was
invalidated: its levels are unknown, not empty, so fetch it again later.
Methods
get
Fetch a one-shot depth snapshot.create_subscription
Managed live book (snapshot + sequence-checked deltas).subscribe_deltas
Raw delta stream (no local merge).
There is no separate subscribe convenience alias, use create_subscription.
Get
Fetches a depth snapshot and returns OrderbookData. Snapshot depths are 1, 5, 10, 20, 50, 100, 200, 500, 1000; a depth in between requests the smallest one that covers
it, and depth on the result reports the depth requested. None / Some(0) request 50. A depth
above 1000 returns Error::Validation before any request.
let book = client.orderbook.get("BTC-USDT", Some(20)).await?;
println!("{:?} {:?} {}", book.bids.first(), book.asks.first(), book.book_seq);Create subscription
Builds a managed live order book: REST snapshot, then Centrifugo deltas with sequence checking.
Gaps trigger a REST refresh. Returns orderbook::Subscription. Consume with updates().recv().await (not TypedSubscription::recv).
use polyester::services::CreateSubscriptionOptions;
let mut sub = client
.orderbook
.create_subscription(CreateSubscriptionOptions {
symbol: "BTC-USDT".into(),
depth: Some(50),
bucket: Some("1.0".into()),
..Default::default()
})
.await?;
while let Some(book) = sub.updates().recv().await {
println!("{} {}", book.book_seq, book.bids.len());
break;
}
sub.set_bucket("5.0")?; // validates and re-aggregates without reconnecting
sub.close();symbol_id is resolved from catalogs when omitted; call wait_for_catalogs().await? first if you
rely on symbol strings.
One-shot snapshots support depth 1000. create_subscription accepts a depth from 1 to 500 and
returns Error::Validation before connecting outside that range.
Buckets must be positive price increments. Bids round down and asks round up, so aggregation never
displays an ask below its executable price or narrows the visible spread artificially.
Malformed snapshots or checked-arithmetic overflow return Error::Validation instead of
panicking, wrapping, or producing levels with missing fields. A malformed delta is rejected
atomically and triggers a snapshot refresh without advancing the local sequence.
create_subscription handles snapshot fetch, sequence gaps, and reconnect refetch.Subscribe deltas
Returns TypedSubscription<OrderBookDeltaUpdate>. Prefer recv_result().await so terminal errors
are not separated from stream closure. Raw deltas are published only at depths 1, 20, 50, 200 and
500 (None means 50); any other depth returns Error::Validation, because raw deltas cannot be
trimmed. Use create_subscription for a book trimmed to any depth up to 500.
let mut deltas = client.orderbook.subscribe_deltas(1, Some(50)).await?;
while let Some(delta) = deltas.recv_result().await? {
println!("{:?}", delta);
break;
}