Skip to content

Binance order book

File: python/binance_order_book.py

Streams BTC/USDT order book depth from Binance WebSocket API.

API Details

Property Value
WebSocket URL wss://stream.binance.com:9443/stream, then SUBSCRIBE btcusdt@depth@100ms (the binance preset's rule for the served topic)
Authentication None (public market data)
Update frequency Every 100ms
Stream type Diff depth (depthUpdate events)
REST snapshot GET https://api.binance.com/api/v3/depth?symbol=BTCUSDT&limit=100 (weight 5; the example keeps the top 20 levels)

What It Does

  1. Fetches the initial order book snapshot from Binance's REST API
  2. Opens the Binance connection as a WebSocketFeed worker that serves the depth-update topic hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT (a world of its own, so no cluster worker reads it): python/websocket_feed.py's serve_topics resolves the topic to the binance preset (market-data-devkit feeds.resolve/apply), creates the feed and polls its status command until it reports connected. The feed sends the SUBSCRIBE on every open, also after a reconnect
  3. The feed routes every depth frame to that topic; the example reads them back through the API gateway's pub/sub
  4. Applies each diff to the local order book; on a gap in the update ids it resyncs from a fresh snapshot (at most every 5 s)
  5. Saves the top 20 levels, best bid/ask and spread to State (statestore / x.examples.binance-order-book.orderbook.BTC_USDT) every 10 s, where Order Flow Imbalance reads them
  6. Deletes the feed on exit (close_feeds), also on Ctrl+C: on the shared demo cluster the connection would otherwise keep streaming

Running

source .env
cd python
uv run python binance_order_book.py

Output (on demo, [depth] lines left out):

============================================================
  Binance order book Example — BTCUSDT Order Book Depth
============================================================

  API:               context demo: api.virtufin.com:443 tls=True key=set
  Stream:            wss://stream.binance.com:9443/stream (btcusdt@depth@100ms)
  State key:         statestore/x.examples.binance-order-book.orderbook.BTC_USDT
  Topic:             hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT

  ✓ Snapshot loaded: 5,000 bids, 5,000 asks (updateId=101295645776)
  → Opening the Binance feed (a WebSocketFeed worker)...
  ✓ Connected: feed worker 59640550-1359-4597-abac-3e1c603a0170, btcusdt@depth@100ms -> hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT
  ⏳ Subscribing to topic via API Gateway: hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT...
  ✓ Initial state saved to: statestore/x.examples.binance-order-book.orderbook.BTC_USDT

  Monitoring depth updates (Ctrl+C to stop)...
      Time      Best Bid      Best Ask    Spread    Lvl
  ────────  ────────────  ────────────  ────────  ─────
  ⚠  Gap detected: expected 101295645777, got 101295646576. Resetting.
  ⏳ Resyncing from a fresh snapshot...
  ✓ Snapshot loaded: 5,000 bids, 5,000 asks (updateId=101295646630)
      10.1s      83909.24      83909.25      0.01     10
      20.1s      83916.71      83916.72      0.01     20

  Stopped after 45s. Saving final state...
  ✓ Feed removed.

The first diff usually arrives after the REST snapshot was taken, so one resync at the start is expected.