Skip to content

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.&lt;interval&gt;]
    K --> BC[BinanceCandles]
    BC --> C[act.exchange.binance.candle.closed.BTC_USDT.&lt;interval&gt;]
    C --> SMA[SimpleMovingAverage<br/>e.g. 7 and 20 days]
    C --> MA[MovingAverageCrossover<br/>strategy]
    SMA --> I[sc.&lt;scenario&gt;.indicator.sma7.changed.BTC_USDT]
    MA --> O[sc.&lt;scenario&gt;.trading.order.submitted]
    O --> SE[SimulatedExecutor]
    SE --> F[sc.&lt;scenario&gt;.trading.order.filled]
  • Candles are world-scoped market data; indicators, orders and fills are scenario-scoped and carry the triggering candle's eventtime.
  • MovingAverageCrossover orders limit orders at the candle's close: SimulatedExecutor fills 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