Crypto Quant System

Production-oriented cryptocurrency quantitative investment system in Python. The first runnable slice is an event-driven BTC/USDT 1h backtest with a 20-period Donchian momentum strategy, local data replay, risk checks, simulated execution, and portfolio accounting.

Architecture

+-------------------------------------------------------------+
|                    Strategy Layer                           |
|  Alpha generation: Donchian momentum, pair trading           |
+-------------------------------------------------------------+
|                    Risk Management Layer                     |
|  Position sizing, drawdown control, throttling, kill switch  |
+-------------------------------------------------------------+
|                    Execution Layer                           |
|  OMS, exchange adapters, TWAP/VWAP, slippage and fee model   |
+-------------------------------------------------------------+
|                    Data & State Layer                        |
|  Market data ingestion, portfolio state, persistence hooks   |
+-------------------------------------------------------------+
|                    Infrastructure Layer                      |
|  Event bus, logging, metrics, exchange connectivity          |
+-------------------------------------------------------------+

Quickstart

python3 main_backtest.py

The command uses config/backtest.yaml and datasets/btc_usdt_1h.csv. The configuration file is valid YAML encoded as JSON so it can run without PyYAML in minimal environments.

Trading Workbench

The operator CLI connects to external market data, previews the Donchian signal, and can run paper trades with persistent local state:

python3 main_trader.py market --symbols BTC/USDT
python3 main_trader.py signal --symbol BTC/USDT --interval 1h --window 20 --quote 100
python3 main_trader.py preflight --symbol BTC/USDT --side BUY --quote 10
python3 main_trader.py paper --symbol BTC/USDT --side BUY --quote 10
python3 main_trader.py paper-portfolio --symbol BTC/USDT
python3 main_trader.py run-once --symbol BTC/USDT --mode preview --quote 100

Market data uses Binance Spot REST first, then Binance.US, then CoinGecko for latest price and OHLC fallback. Paper-trading state is stored under state/ and ignored by git.

Signed exchange checks and live order submission are intentionally gated:

export BINANCE_API_KEY="..."
export BINANCE_API_SECRET="..."
python3 main_trader.py account
python3 main_trader.py test-order --symbol BTC/USDT --side BUY --quote 10 --confirm-test
export CQ_ENABLE_LIVE_TRADING=true
python3 main_trader.py live-order --symbol BTC/USDT --side BUY --quote 10 --confirm-live

preflight fetches exchange trading rules from exchangeInfo, normalizes quantity and price to symbol filters, checks minimum notional, then runs local risk limits. If exchange rules are unavailable, it returns a structured rejection instead of sending anything. test-order calls Binance's signed test-order endpoint and does not create a real order.

Use an exchange endpoint that is legal and available in your jurisdiction. You can switch the public market base URL with CQ_BINANCE_BASE_URL, for example https://api.binance.us.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,monitoring]"

Tests

pytest

The core execution and risk tests are designed for deterministic behavior. The current workspace may not have pytest or all optional dependencies installed; the package itself declares them in pyproject.toml.

Live Mode

CQ_DRY_RUN=true python3 main_live.py

Live trading defaults to dry-run. API keys are loaded from environment variables such as BINANCE_API_KEY and BINANCE_API_SECRET; keys are never stored in source code or configuration files.

This software is trading infrastructure, not financial advice. Every live order path requires explicit operator confirmation and the environment kill switch CQ_ENABLE_LIVE_TRADING=true.