Skip to content

Example Overview

Every example is a client of the Virtufin API gateway. It connects through a context (demo by default) and reaches the platform's services through it: WorkManager (and the WebSocketFeed workers it runs), State and pub/sub.

flowchart LR
    subgraph Examples
        NB[C# notebooks<br/>dotnet/*.verso]
        PY[Python scripts<br/>python/]
        TS[TypeScript<br/>typescript/examples/]
    end

    CTX[contexts.toml<br/>demo / local]
    API[API gateway<br/>gRPC]

    subgraph Platform
        WM[WorkManager<br/>+ Runtime workers]
        WSF[WebSocketFeed workers<br/>one per connection]
        STATE[(State)]
        PUBSUB[(Pub/sub topics)]
    end

    BINANCE[Binance]
    ALPACA[Alpaca]

    NB & PY & TS -.->|name| CTX
    NB & PY & TS -->|TLS + x-api-key on demo| API
    API --> WM & STATE & PUBSUB
    WM -->|CreateWorker| WSF
    WSF -->|wss://| BINANCE & ALPACA
    WSF -->|publishtopic| PUBSUB
    PUBSUB --> WM

C# notebooks (dotnet/)

Verso notebooks, listed with what each one covers in the dotnet README. See C# for running them.

Group Notebooks Deploys on the platform
Devkits end to end market-data-devkit, indicator-devkit, strategy-devkit, execution-devkit Yes: writes a worker (dotnet/workers/), tests it offline on real Binance data, publishes it to the feed, deploys it on demo next to the published workers; Cleanup removes everything
Workers chained, offline worker-pipeline-offline No: BinanceCandles → SimpleMovingAverage / MovingAverageCrossover → SimulatedExecutor, in-process on real klines
Live platform pipelines binance-order-book-live, indicators-live Yes: deploys the published workers on a live Binance feed and charts their events
Latency measurement binance-order-book-harness Yes: the same order-book pipeline fed by the fixed-rate fake venue (harness/fake-venue); the only load a latency A/B can trust
Latency measurement (Alpaca) alpaca-order-book-harness Yes: AlpacaOrderBook on 50 USD pairs against the fake venue's /alpaca protocol; each feed (the fakevenue-alpaca preset) logs in and serves its book worker's update topics
Indicators at scale indicators-50-pairs-live Yes: all five indicator workers on 50 pairs, fed by five sharded BinanceCandles instances, each with a kline feed serving its slice's raw topics; prints each worker's value per pair and reads the state keys
Trade flow trade-flow-live Yes: the venue's trade tape sharded across workers, folded by TradeFlow into units / quote notional / trades per pair over a time window, with publish and save pacing; one Venue const switches Binance and Alpaca
Strategy as C# text moving-average-crossover-kelly Yes: backtests a Kelly-sized crossover on real Binance daily candles, then deploys its own worker cells to demo as C# source (text/x-csharp, no package), replays the candles through it and a SimulatedExecutor, and checks the orders against the backtest; Cleanup removes both
Sharded groups shard-groups Yes: three copies of one C# source worker on a topic with shard_index 0..2; keyed events produce one marker each, a duplicate index is refused, and Cleanup removes the workers
Worker workflow breakout-worker-workflow Yes: develops a breakout strategy and a fills-to-positions worker in the notebook, unit tests them, runs them with SimulatedExecutor on a local WorkManager, deploys the same cells as C# text, replays the candles on the cluster and checks the cluster run against the local one; Cleanup removes the three workers
Binance testnet, end to end binance-testnet-end-to-end Yes: one strategy on the Binance spot testnet with every part: the testnet kline feed and BinanceCandles, the strategy (its own cells as C# text), LiveExecutor placing real testnet orders, the account stream with BinanceOrderUpdates and BinancePortfolio, and BinancePositionReconciler recovering the strategy after its executor stops; Cleanup removes all eight workers
Devkit and library tours behavior-devkit, cloudevent-envelope-extensions, naming, core-base, signals-indicators No

A notebook that can't reach its context's gateway still runs: the steps that need the platform report [skipped].

Python (python/)

Example What it does
Binance order book A WebSocketFeed worker on Binance depth, published to a topic and read back to keep a local order book; top 20 levels saved to State
Alpaca order book The same for Alpaca's BTC/USD order book; the feed (the alpaca preset) logs in from worker secrets
Order Flow Imbalance Reads the Binance order book from State (written by Binance order book) and computes the weighted bid/ask imbalance
python/worker_workflow.py A marimo notebook for the worker workflow in Python: an SMA indicator, a long-only crossover strategy and a fill-to-position worker, unit tested, run locally with the published SimulatedExecutorPython on LocalWorkManager, deployed as worker wheels built from its own cells, replayed on the cluster and compared with the local run; its last cell removes the workers
python/shard-groups.py Three identical workers split one topic with shard_index 0..2: every event produces exactly one marker, two events with the same subject land on the same member, and a duplicate index is refused at StartWorker
python/api.py A marimo notebook touring the Python client: connect, service discovery, config, State, pub/sub, triggers, WorkManager and WebSocketFeed workers. It writes a key, events and a trigger under its own x.examples.api.* names and its Cleanup cell removes them

TypeScript (typescript/examples/)

Script npm script What it does
api.ts npm run api State save, get and delete through the gateway
websocketfeed.ts npm run websocketfeed A WebSocketFeed worker on Binance depth, published to a topic, its status read, then deleted
workmanager.ts npm run workmanager Lists, creates and removes WorkManager workers
typescript-worker.ts npm run typescript-worker TypeScript workers on the WorkManager's TypeScript engine: deploys workers/greeter.mts (a devkit CommandWorker: answers greet, heartbeat from its own loop) and one workers/pair-monitor.mts per pair on the pairs' order-book topics (the feeds that serve them opened by the script), reads the greeting, heartbeats and per-pair summaries, stops the greeter, removes everything

See TypeScript.

Key Concepts

Concept Where it shows up
Context A ContextName / CONTEXT_NAME constant at the top of every example, looked up in ~/.config/virtufin/api/contexts.toml
WebSocket connection A WebSocketFeed worker that serves topics: the topics the workers listen to go to market-data-devkit's resolver (FeedResolver, feeds.resolve), which plans the feeds from the venue presets, and the orchestrator (FeedOrchestrator, feeds.apply) creates them (workmanager.CreateWorker + StartWorker, config topics + the preset) or serves running ones their topics (InvokeWorkerCommand serve); DeleteWorker when done
Pub/sub Examples subscribe to the topic through the gateway (pubsub.subscribe_async_iter); a subscription starts at the topic's tail, so subscribe before the feed opens and the exchange sends its first message
State save_state / get_state on statestore, a service the gateway registers on demo and local; the keys are the examples' own (x.examples.…)
Workers Packages on the Virtufin feed, deployed with workmanager.CreateWorker / StartWorker; every worker on a topic gets every message
Envelope CloudEvent extensions on every event: world-scoped market data (act.exchange.…), scenario-scoped indicators, orders and fills (sc.<scenario>.…)
Shared demo cluster Examples remove what they create (feed workers, workers, published test packages)
Bid/ask imbalance Σ ask_price × ask_qty − Σ bid_price × bid_qty over the top N levels