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>
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/) 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)

Run the backend with deploy-local (prerequisites in its README, more in Deployment):

cd deploy-local
./scripts/deploy.sh   # builds and starts every service, waits until healthy

4. Install Dependencies

See Installation for detailed per-language instructions.

5. Run Examples

# Binance order book (Python)
cd python && source ../.env
export UV_INDEX_VIRTUFIN_USERNAME=$VIRTUFIN_REGISTRY_USER
export UV_INDEX_VIRTUFIN_PASSWORD=$VIRTUFIN_REGISTRY_TOKEN
uv run python binance_order_book.py

# Order Flow Imbalance (Python)
uv run python orderflow_imbalance.py

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