Skip to content

Getting Started

Prerequisites

Component Version Purpose
Python 3.11+ Running Python examples
.NET SDK 10.0 Building C#/F# examples
Node.js 20+ Running TypeScript examples
Docker Latest Running Virtufin services locally (only for the local context)
Dapr CLI 1.17+ Service mesh for state store and pub/sub (only for the local context)

Setup Steps

1. Configure Gitea Registry Access

Create a Gitea personal access token with read:packages scope:

cp .env.example .env
# Edit .env:
#   VIRTUFIN_REGISTRY_USER=<your-username>
#   VIRTUFIN_REGISTRY_TOKEN=<your-token>
#   ALPACA_API_KEY=<optional>
#   ALPACA_API_SECRET=<optional>
source .env

2. Choosing the API: contexts

Every example talks to one Virtufin API, named by a context. Each example sets the name as a constant near its top, "demo" by default, with an explanation:

Example Constant
.NET notebooks (dotnet/*.verso) const string ContextName = "demo";
Python (python/, scripts/) CONTEXT_NAME = "demo"
TypeScript (typescript/examples/) const CONTEXT_NAME = "demo";

The name is looked up in ~/.config/virtufin/api/contexts.toml ($XDG_CONFIG_HOME-aware), the file virtufin-tui reads too:

[[contexts]]
name = "demo"
api_host = "api.virtufin.com"
api_port = 443
tls = true
api_key = "<your-demo-api-key>"

[[contexts]]
name = "local"
api_host = "localhost"
api_port = 5002
tls = false
  • demo is the shared cluster: nothing to start, but you need an API key (ask an admin; it can also come from the VIRTUFIN_API_KEY environment variable instead of the file). The examples clean up what they create, because other people use the same cluster.
  • local is a backend you run yourself (step 3). Change the constant to "local".
  • A name the file doesn't have connects to localhost:5002, plaintext, without a key.

3. Start Virtufin Services (only for local)

docker compose up -d

Wait for the API gateway to become healthy:

curl http://localhost:5001/health

4. Install Dependencies

See Installation for detailed per-language instructions.

5. Run Examples

# Binance CLOB (Python)
cd python && source ../.env
export UV_INDEX_VIRTUFIN_USERNAME=$VIRTUFIN_REGISTRY_USER
export UV_INDEX_VIRTUFIN_PASSWORD=$VIRTUFIN_REGISTRY_TOKEN
uv run python websocketmanager/binance_clob_example.py

# Order Flow Imbalance (Python)
uv run python workmanager/orderflow_imbalance_worker.py

See the examples section for all available examples and their outputs.