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
- Starts a listener on
hyp.EXAMPLES.exchange.alpaca.orderbook.update.BTC_USDbefore creating the feed: pub/sub starts at the topic's tail, and the full book comes right after the subscribe - Opens the feed that serves that topic (the
alpacapreset subscribes BTC/USD's order book and routes its messages there) and waits until it is connected - Applies the full book and each update to a local order book
- Saves the top 20 levels and spread to State (
statestore/x.examples.alpaca-order-book.orderbook.BTC_USD) every 10 s - 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