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: WebSocketManager, WorkManager, State and pub/sub.

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

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

    subgraph Platform
        WSM[WebSocketManager]
        WM[WorkManager<br/>+ Runtime workers]
        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 --> WSM & WM & STATE & PUBSUB
    WSM -->|wss://| BINANCE & ALPACA
    WSM -->|StartPublish| 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 engines; Cleanup removes everything
Engines chained	devkit-pipeline	No: BinanceCandles → SimpleMovingAverage / MovingAverage → SimulatedExecutor, in-process on real klines
Live platform pipelines	binance-order-book-live, indicators-live	Yes: deploys the published engines on a live Binance feed and charts their events
Devkit and library tours	behavior-devkit, cloudevent-envelope-extensions, virtufin-core-base, virtufin-signals-indicators, moving-average-crossover-kelly	No

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

Python (python/, scripts/)

Example	What it does
Binance CLOB	WebSocketManager connection to Binance depth, published to a topic and read back to keep a local order book; top 20 levels saved to State
Alpaca CLOB	The same for Alpaca's BTC/USD order book, with API-key auth sent over the WebSocket
Alpaca Market Data	Five Alpaca crypto symbols into one topic, every frame printed
Order Flow Imbalance	Reads the Binance order book from State (written by Binance CLOB) and computes the weighted bid/ask imbalance
python/API.py	A marimo notebook touring the Python client: connect, service discovery, config, State, pub/sub, triggers, WorkManager and WebSocketManager. It writes demo-/demo. keys, events, a trigger and a worker and leaves them for you to inspect

TypeScript (typescript/examples/)

Script	npm script	What it does
api_example.ts	npm run api	State save, get and delete through the gateway
websocketmanager_example.ts	npm run wsm	A WebSocketManager connection to Binance, published to a topic, listed, then disconnected
workmanager_example.ts	npm run wm	Lists, creates and removes WorkManager workers

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	websocketmanager.Connect (with auto_reconnect), SendRaw for subscribe/auth messages, StartPublish to a topic, Disconnect 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 and publish before the exchange's first message
State	save_state / get_state on a service the gateway registers (statestore, websocketmanager)
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 (connections, workers, published test packages)
Bid/ask imbalance	Σ ask_price × ask_qty − Σ bid_price × bid_qty over the top N levels