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, best-first (bids descending, asks ascending). Each snapshot
carries BookSeq, the backend sequence number used to detect gaps.
Methods
| Method | Summary |
|---|---|
Get | Fetch a one-shot depth snapshot. |
CreateSubscription | Managed live book (snapshot + sequence-checked deltas). |
Subscribe | Convenience wrapper around CreateSubscription. |
SubscribeDeltas | Raw delta stream (no local merge). |
Get(ctx, symbol, depth)
Fetches a depth snapshot and returns models.OrderbookData. Exact supported depths are 1, 5, 10, 20, 50, 100, 200, 500, 1000; intermediate requests round up to the next supported
depth, and Depth on the result is the depth requested. 0 means 50; a depth below 0 or above 1000 returns *errors.ValidationError before any request. Catalog hydration is required because decoded quantities need the pair's base scale.
book, err := client.Orderbook.Get(ctx, "BTC-USDT", 20)
if err != nil { log.Fatal(err) }
fmt.Println(book.Available, len(book.Bids), len(book.Asks), book.BookSeq)Available is true when the book is current, so an empty side means no liquidity. It is false while
the market's book is being built or after it was invalidated: its levels are unknown, not empty, so
request the snapshot again later.
CreateSubscription(ctx, opts) / Subscribe(...)
Builds a managed live order book: REST snapshot, then Centrifugo deltas with sequence checking.
Gaps trigger a REST refresh. Returns *orderbook.Subscription.
Managed books expose Updates(), not Messages() (that name is for typed *realtime.Subscription[T] helpers).
import "github.com/Fabric-Labs/polyester-sdk-go/services"
sub, err := client.Orderbook.CreateSubscription(ctx, services.CreateSubscriptionOptions{
Symbol: "BTC-USDT",
Depth: 50,
Bucket: "1.0",
OnEvent: func(book models.OrderbookData) {
fmt.Println(book.BookSeq, len(book.Bids), len(book.Asks))
},
})
if err != nil { log.Fatal(err) }
defer sub.Close()
for book := range sub.Updates() {
fmt.Println(book.BookSeq)
break
}
sub.SetBucket("5.0") // re-aggregate without reconnectingSymbolID is resolved from catalogs when omitted; call WaitForCatalogs first if you rely on
symbol strings. Optional: OnSequenceGap, OnReconnect, OnSnapshotRefresh, OnError.
One-shot snapshots support depth 1000; managed books take a depth from 1 to 500 (0 means 50). A managed book subscribes to the smallest published stream depth covering yours (1, 20, 50, 200, or 500) and trims each view to the depth you asked for.
Buckets must be positive price increments. Bids round down and asks round up, preserving
executable spread semantics. Malformed snapshots and integer overflow terminate the local render
with a validation error. A malformed delta is rejected atomically and triggers a snapshot refresh
without advancing the local sequence.
CreateSubscription handles snapshot fetch, sequence gaps, and reconnect refetch.SubscribeDeltas(ctx, symbolID, depth)
Returns *realtime.Subscription[models.OrderBookDeltaUpdate], consume with Messages(). Raw
deltas can't be trimmed, so depth must be a published stream depth (1, 20, 50, 200, or 500); any other depth returns *errors.ValidationError before connecting.
deltas, err := client.Orderbook.SubscribeDeltas(ctx, 1, 50)
if err != nil { log.Fatal(err) }
defer deltas.Close()
for d := range deltas.Messages() {
fmt.Println(d.BookSeqStart, d.BookSeqEnd)
break
}