Data Flow
Binance order book and Order Flow Imbalance (Python)
binance_order_book.py keeps a local BTC_USDT order book from Binance's depth stream and saves its top 20
levels to State. orderflow_imbalance.py reads that state and computes the imbalance.
sequenceDiagram
participant Binance
participant Feed as WebSocketFeed worker<br/>(WorkManager Runtime)
participant API as API gateway
participant Clob as binance_order_book.py
participant Imb as orderflow_imbalance.py
Note over Clob: feeds.resolve: the topic hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT<br/>matches the binance preset
Clob->>API: workmanager.CreateWorker WebSocketFeed (the binance preset, topics [that topic])
Clob->>API: workmanager.StartWorker
Feed->>Binance: open, then SUBSCRIBE btcusdt@depth@100ms (on every open)
Clob->>API: InvokeWorkerCommand status (until connected)
Clob->>API: subscribe hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT
Binance->>Feed: depthUpdate (every 100 ms)
Feed->>API: publish frame to the topic (routed by its stream)
API-->>Clob: depth event
Note over Clob: Applies the diff to the local book<br/>(REST snapshot from Binance on a gap)
loop Every 10 s
Clob->>API: save_state statestore/x.examples.binance-order-book.orderbook.BTC_USDT (top 20 + spread)
end
loop Every 2 s
Imb->>API: get_state statestore/x.examples.binance-order-book.orderbook.BTC_USDT
Note over Imb: New lastUpdateId? Compute weighted imbalance
Imb->>API: save_state statestore/x.examples.orderflow-imbalance.BTC_USDT
end
Clob->>API: workmanager.DeleteWorker (on exit: feeds.delete by owner)
orderflow_imbalance.py has no connection of its own: it reads only the state written by
binance_order_book.py, which must be running.
Alpaca order book (Python)
sequenceDiagram
participant Alpaca
participant Feed as WebSocketFeed worker<br/>(WorkManager Runtime)
participant API as API gateway
participant Ex as alpaca_order_book.py
Ex->>API: subscribe hyp.EXAMPLES.exchange.alpaca.orderbook.update.BTC_USD
Ex->>API: workmanager.CreateWorker WebSocketFeed (the alpaca preset:<br/>URL, login step, subscription template; topics [that topic], secrets alpacakey/alpacasecret)
Ex->>API: workmanager.StartWorker
Note over Feed: The Runtime resolves the worker secrets<br/>(alpaca-paper-key, alpaca-paper-secret)
Feed->>Alpaca: {"action":"auth",…} (on every open)
Feed->>Alpaca: {"action":"subscribe","orderbooks":["BTC/USD"]}
Alpaca->>Feed: full book (r=true), then updates
Feed->>API: publish message to hyp.EXAMPLES.exchange.alpaca.orderbook.update.BTC_USD (routed by T,S)
API-->>Ex: frame
Note over Ex: Applies it to the local book
loop Every 10 s
Ex->>API: save_state statestore/x.examples.alpaca-order-book.orderbook.BTC_USD
end
Ex->>API: workmanager.DeleteWorker (on exit: feeds.delete by owner)
The order matters: a topic subscription starts at the topic's tail, and Alpaca's first message after the subscribe is the full book, so the example subscribes to the topic before it creates the feed, which logs in and subscribes at Alpaca as soon as it opens. The keys never pass through the script: the feed reads them from its worker secrets.
Worker pipeline (C# notebooks)
The devkit notebooks deploy the published workers on demo; worker-pipeline-offline.verso runs the same chain
in-process on real Binance klines.
flowchart LR
BIN[Binance klines] -->|WebSocketFeed worker| K[act.exchange.binance.candle.update.BTC_USDT.<interval>]
K --> BC[BinanceCandles]
BC --> C[act.exchange.binance.candle.closed.BTC_USDT.<interval>]
C --> SMA[SimpleMovingAverage<br/>e.g. 7 and 20 days]
C --> MA[MovingAverageCrossover<br/>strategy]
SMA --> I[sc.<scenario>.indicator.sma7.changed.BTC_USDT]
MA --> O[sc.<scenario>.trading.order.submitted]
O --> SE[SimulatedExecutor]
SE --> F[sc.<scenario>.trading.order.filled]
- Candles are world-scoped market data; indicators, orders and fills are scenario-scoped and carry the
triggering candle's
eventtime. MovingAverageCrossoverorders limit orders at the candle's close:SimulatedExecutorfills limit orders only.- Every worker subscribed to a topic gets every message on it.
State Keys
The scripts' keys are their own, outside every published contract, so they live in the naming
library's experimental scope x.* (lib.docs.virtufin.com/naming).
The order-book topics the Python feeds serve are market topics in a hypothetical world of their own,
hyp.EXAMPLES, so no worker on the cluster reads them.
Pairs are canonical (BTC_USDT, BTC_USD); the venue's own symbol appears only where a script talks to it.
| Service / key | Written by | Content |
|---|---|---|
statestore / x.examples.binance-order-book.orderbook.BTC_USDT |
binance_order_book.py |
Top 20 bids/asks, best bid/ask, spread, lastUpdateId |
statestore / x.examples.alpaca-order-book.orderbook.BTC_USD |
alpaca_order_book.py |
Top 20 bids/asks and spread |
statestore / x.examples.orderflow-imbalance.BTC_USDT |
orderflow_imbalance.py |
Weighted bids/asks, imbalance, spread, pressure signal |
The gateway accepts only the services it registers (statestore, workmanager).
Topics used by the scripts
| Topic | Published by (a WebSocketFeed worker the script creates) | Read by |
|---|---|---|
hyp.EXAMPLES.exchange.binance.orderbook.update.BTC_USDT |
binance_order_book.py |
binance_order_book.py |
hyp.EXAMPLES.exchange.binance.orderbook.update.<PAIR> (BTC_USDT, ETH_USDT, SOL_USDT) |
websocketfeed.ts |
websocketfeed.ts (counts the frames per pair) |
hyp.EXAMPLES.exchange.alpaca.orderbook.update.BTC_USD |
alpaca_order_book.py |
alpaca_order_book.py |
hyp.EXAMPLES.exchange.binance.orderbook.update.<PAIR> (BTC_USDT, ETH_USDT) |
typescript-worker.ts (its feeds) |
workers/pair-monitor.mts, one TypeScript worker per pair |
x.examples.typescript-worker.greet / .greeting |
typescript-worker.ts (a greet command) / workers/greeter.mts |
workers/greeter.mts / typescript-worker.ts |
x.examples.typescript-worker.heartbeat |
workers/greeter.mts (its own loop, every second) |
typescript-worker.ts |
x.examples.typescript-worker.summary.<PAIR> |
workers/pair-monitor.mts (every 2 s) |
typescript-worker.ts |