VPIN Lab

Standalone Python toolkit for Volume-Synchronized Probability of Informed Trading (VPIN) research on crypto trade data. The package includes a CCXT-backed data connector, offline VPIN pipeline APIs for in-memory data, backtesting utilities, and a self-contained lab runner with grid, random, Bayesian-style, and Hyperband-style parameter search.

Scope

• External market data ingestion is CCXT only.
• No API key is required for public exchange trade data on exchanges that expose it through CCXT.
• Optional CCXT credentials are read from CLI arguments or environment variables and are not written by the toolkit.
• The lab search implementation is included in this repository and does not require an external alpha research driver.
• Runtime dependencies are CPU-only: ccxt, numpy, pandas, pydantic, PyYAML, scipy, and matplotlib.
• Generated data snapshots, logs, caches, build products, and sample artifacts are intentionally not committed.

Install With uv

uv venv .venv
uv pip install -e ".[dev]"

For a minimal runtime install:

uv venv .venv
uv pip install -e .

CLI Usage

Run a direct VPIN analysis from CCXT:

.venv/bin/vpin-analyze \
  --source ccxt \
  --exchange-id binance \
  --symbol BTC/USDT \
  --start-date 2024-01-01 \
  --end-date 2024-01-02 \
  --output output/vpin_results.csv

Optional credentials can be supplied with --api-key, --api-secret, VPIN_CCXT_API_KEY, and VPIN_CCXT_SECRET when an exchange endpoint requires authentication.

Python Usage

Use CCXT for packaged ingestion:

from vpin_lab import CCXTConnector, VPINConfig, VPINPipeline

config = VPINConfig(bucket_volume_size=1000, window_length=50)
connector = CCXTConnector(exchange_id="binance")
pipeline = VPINPipeline(config=config, data_connector=connector)

result = pipeline.run(
    symbol="BTC/USDT",
    start_date="2024-01-01",
    end_date="2024-01-02",
)
print(result.mean_vpin)

Use run_from_dataframe when trade data is already loaded in memory:

from vpin_lab import VPINConfig, VPINPipeline

pipeline = VPINPipeline(config=VPINConfig())
result = pipeline.run_from_dataframe(trades_df, symbol="BTC/USDT")

Expected trade columns are timestamp, price, quantity, and optionally side or exchange maker-side metadata.

Lab Workflow

Create a standalone experiment template:

.venv/bin/vpin-lab init --output experiments.yaml

Run one experiment:

.venv/bin/vpin-lab run --config experiments.yaml

Run a parameter sweep:

.venv/bin/vpin-lab sweep --config experiments.yaml

The bundled template uses search.algorithm: bayes_heuristic, which is implemented in vpin_lab.lab.search.bayes and works without external services.

Test And Build

uv pip install -e ".[dev,parquet]"
.venv/bin/python -m pytest
.venv/bin/python -m build

Before publishing, inspect the built archives:

tar -tf dist/vpin_lab-*.tar.gz
unzip -l dist/vpin_lab-*.whl

The archives should contain package source, the lab template, the tracking schema, metadata, README, and LICENSE only. They should not include local caches, logs, snapshots, or generated analysis artifacts.

Package Layout

• vpin_lab/data_sources: CCXT connector and shared data models.
• vpin_lab/core: preprocessing, trade classification, bucketing, volatility, and VPIN calculation.
• vpin_lab/pipeline.py: high-level VPIN pipeline APIs.
• vpin_lab/backtest, strategy, risk, execution: research and simulation utilities.
• vpin_lab/lab: experiment config schema, tracking store, split handling, backtesting runner, export policy, and parameter search.
• tests: offline unit and integration tests with mocked or in-memory data.