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 |