client.orderbook reads spot depth snapshots and maintains a stateful live book. It uses the
public transport, so no authentication is required.
Levels are { price, qty } pairs (decimal / money types), best-first (bids descending, asks
ascending). Each snapshot carries book_seq, the backend sequence number used to detect gaps.
Methods
| Method | Summary |
|---|---|
get | Fetch a one-shot depth snapshot. |
create_subscription | Managed live book (snapshot + sequence-checked deltas). |
subscribe | Convenience wrapper around create_subscription. |
subscribe_deltas | Raw delta stream (no local merge). |
Get
Fetches a depth snapshot for a symbol and returns OrderbookData. depth defaults to 50 and is
snapped to a supported level (1, 5, 10, 20, 50, 100, 200, 500, 1000).
book = await client.orderbook.get(symbol="BTC-USDT", depth=20)
print(book.bids[0], book.asks[0], book.book_seq)Create subscription and subscribe
Builds a managed live order book: REST snapshot, then Centrifugo deltas with sequence checking.
Gaps or reconnects trigger a REST refresh so you always see a consistent book. Returns an OrderbookSubscription (async-iterable).
One-shot snapshots support depth 1000; managed realtime channels are capped at depth 500.
sub = await client.orderbook.create_subscription(
symbol="BTC-USDT",
depth=50,
bucket="1.0", # optional local price aggregation
)
async with sub:
async for book in sub:
print(book.bids[0], book.asks[0], book.book_seq)
break
# Re-bucket without reconnecting
sub.set_bucket("5.0")symbol_id is resolved from catalogs when omitted; await wait_for_catalogs() first if you rely
on symbol strings. Optional callbacks: on_event, on_open, on_close, on_error, on_sequence_gap, on_reconnect, on_snapshot_refresh.
create_subscription handles snapshot fetch, sequence gaps, and reconnect refetch.
Use raw subscribe_deltas only when you maintain your own book.Subscribe deltas
deltas = await client.orderbook.subscribe_deltas(symbol_id=1, depth=50)
async with deltas:
async for delta in deltas:
print(delta.book_seq_start, delta.book_seq_end)
breakShapes
OrderbookData: symbol, depth, book_seq (string), bids / asks as OrderbookLevel (price, qty). Pass bucket (or call set_bucket) to aggregate into coarser price buckets; None / empty clears bucketing. Bids round down and asks round up, preserving executable spread
semantics. Malformed snapshots raise PolyesterValidationError instead of returning corrupted
data. A malformed delta is rejected atomically and triggers a snapshot refresh without advancing
the local sequence.