Skip to content

Alpaca order book

File: python/alpaca_order_book.py

Streams BTC/USD order book from Alpaca crypto WebSocket, logged in from worker secrets.

API Details

Property Value
WebSocket URL wss://stream.data.alpaca.markets/v1beta3/crypto/us
Authentication Message-based: {"action":"auth","key":"...","secret":"..."}
Subscribe {"action":"subscribe","orderbooks":["BTC/USD"]}
Order book type L3 (full depth)
Keys Paper-trading keys work on the market-data stream

Authentication Flow

Unlike Binance where the stream is public, Alpaca expects a login on every new socket, within 10 seconds. The connection is a WebSocketFeed worker, run by the WorkManager Runtime, and it logs in by itself on every socket open (the first connect, every reconnect, every move to another Runtime pod). The feed knows no venue: its config is the alpaca preset of market-data-devkit, whose login step sends the auth message with {secret:alpacakey}/{secret:alpacasecret} filled in, waits for "msg":"authenticated" (any "T":"error" fails the login, which is retried), and whose subscription template then subscribes the order books of the topics it serves.

The keys come from the feed's worker secrets alpacakey and alpacasecret (CreateWorkerRequest.secrets): references into the cluster's worker Secret, resolved by the Runtime. The example passes only the reference names, never the keys:

ALPACA_SECRETS = {"alpacakey": "alpaca-paper-key", "alpacasecret": "alpaca-paper-secret"}

applied = await serve_topics(api, [DEPTH_TOPIC], FEED_OWNER, secrets={"alpaca": ALPACA_SECRETS})

serve_topics (python/websocket_feed.py) hands the topic (hyp.EXAMPLES.exchange.alpaca.orderbook.update.BTC_USD, in a world of its own so no cluster worker reads it) to market-data-devkit's feeds.resolve, which matches it to the alpaca preset, and feeds.apply creates and starts the feed through the gateway (workmanager.CreateWorker + StartWorker); then it polls the feed's status command until it reports connected, which means logged in and subscribed. The keys never pass through the script or pub/sub, so nothing needs to be set locally; on demo the Secret holds paper-trading keys.

Alpaca allows one stream connection per account: close other streams on the same keys first.

What It Does

  1. Starts a listener on hyp.EXAMPLES.exchange.alpaca.orderbook.update.BTC_USD before creating the feed: pub/sub starts at the topic's tail, and the full book comes right after the subscribe
  2. Opens the feed that serves that topic (the alpaca preset subscribes BTC/USD's order book and routes its messages there) and waits until it is connected
  3. Applies the full book and each update to a local order book
  4. Saves the top 20 levels and spread to State (statestore / x.examples.alpaca-order-book.orderbook.BTC_USD) every 10 s
  5. Deletes the feed on exit (close_feeds), which closes the socket and frees Alpaca's one connection

For a worker that maintains the books on the platform, with a live depth chart, see the alpaca-order-book-live.verso notebook: its AlpacaOrderBook workers subscribe to their pairs' update topics, and the notebook opens one feed that serves them all (ServeTopicsAsync).

Running

source .env
cd python
uv run python alpaca_order_book.py