QuantDesk

English · 简体中文

Minimal Personal US Equities Quant Desk
Research → Alpha Wash → Paper → Live-ready (fail-closed)
一人可跑通 · 假 alpha 硬淘汰 · 实盘默认硬锁

---

Public OSS snapshot (quantdesk-oss). Sanitized open-source edition — no live credentials, journals, or private research dumps. Copy .env.example → .env, set a strong ADMIN_PASSWORD, then run.

Get the code

1. Clone: git clone https://github.com/leohux/quantdesk-oss.git
2. Download package: latest Release → Source code (zip / tar.gz) on the right sidebar

QuantDesk is a minimal, solo-operator open-source quant desk for US equities — small enough for one person to run end-to-end, without hedge-fund infrastructure. It does not just backtest; it tries to kill fake alpha before money is at risk:

Stage	What you get
Research / Backtest	VectorBT (+ pandas fallback), shared signal interface, walk-forward friendly
Alpha Wash	Hard gates: robustness → survivorship → point-in-time universe → reality costs → factor attribution
Paper	Alpaca paper broker, brackets / OCO, portfolio risk gates
Live (IBKR)	Gateway in private Docker network, readiness console, fail-closed by default

⚠️ Not financial advice. Trading involves risk of loss. This software is provided as-is for research and education. Live submission stays locked until you deliberately unlock multiple independent gates.

---

Product tour

More screenshots — strategy lab and paper trading

Screenshots show a paper-trading environment with illustrative account data. No live-broker credentials or private infrastructure are included.

---

Why QuantDesk?

Most "quant dashboards" glue a chart to a broker SDK and call it done. QuantDesk is built around a few non-negotiables:

• Alpha wash before capital — programmatic gates reject overfit, survivorship bias, look-ahead universes, unrealistic costs, and beta dressed up as alpha (research_reviewer/, hard-gate scripts)
• One strategy interface — the same generate_signals(close, params) → (entries, exits) runs in backtest, paper, and live runners
• Event-driven core — MarketData → Signal → Risk → Order → Fill over an EventBus
• Pluggable execution — swap Paper / Alpaca / IBKR without rewriting strategies
• Pre-trade risk — every order passes RiskEngine before any broker; brackets / OCO on paper
• Live is fail-closed — UI clicks and normal API calls cannot place real orders by accident
• Ops-ready — Docker Compose, Postgres, Redis, Nginx sample, Telegram notifications

---

Architecture

flowchart LR
  subgraph UI
    W[Vite + React Dashboard]
  end
  subgraph API
    F[FastAPI]
    A[Auth / Audit]
  end
  subgraph Core
    E[EventBus]
    S[Strategy Engine]
    R[Risk Engine]
    O[OMS]
  end
  subgraph Execution
    P[Paper Engine]
    AL[Alpaca Paper]
    IB[IBKR Adapter<br/>fail-closed]
  end
  subgraph Data
    YF[yfinance]
    AP[Alpaca Data]
    DB[(Postgres)]
  end

  W --> F
  F --> A
  F --> E
  E --> S --> R --> O
  O --> P
  O --> AL
  O --> IB
  S --> YF
  S --> AP
  F --> DB

Loading

Deep dive: docs/Architecture.md · docs/EventFlow.md

---

Features

Trading core

• Shared strategy ABC + code strategies (core/strategy/)
• Backtest engine with VectorBT / pandas (core/backtest/)
• Paper execution simulator + Alpaca paper client (brackets / OCO)
• IBKR live adapter with reconnect + status mapping (core/execution/ibkr.py)
• Live guard + OMS reconcile + audit JSONL (core/trading/live_guard.py, live_oms_service.py)

Alpha wash / research gates

• Rule engine with stable reject codes: overfit, walk-forward fail, param instability, survivorship, PIT universe, reality costs, no independent alpha (research_reviewer/research_gates.py)
• Hard Gate 8–11 scripts: survivorship + WF → point-in-time S&P → reality/cost/concentration → factor attribution
• Strategy status registry archives failed “pretty backtests” so they cannot quietly re-enter live
• Optional LLM-assisted alpha miner + research reviewer agents (proposal only — still must pass gates)

Product surfaces

• Dashboard / Strategy Lab / Backtest / Paper / Live (LOCKED) / Settings
• REST API (/api/*) + OpenAPI at /docs
• EventBus path: market data → signal → risk → order → fill

Safety

• Multi-gate live unlock (LIVE_TRADING_ENABLED ∧ LIVE_EXECUTION_ARMED ∧ arming token ∧ admin)
• Symbol / side whitelist, hard notional & exposure caps
• Kill switch + structured audit log
• Secrets stay in .env (repo ships .env.example only)

---

Quick Start

Double-click after unzip (Windows)

1. Install and start Docker Desktop (wait until it is green)
2. Double-click 打开QuantDesk.bat (or start.bat)
3. First launch builds images; the browser opens http://127.0.0.1:18080
4. Stop with 关闭QuantDesk.bat / stop.bat

Short Chinese guide: 使用说明.txt. The launcher copies .env.example → .env if missing (default ADMIN_PASSWORD=changeme1 — change it). Without Docker, it falls back to local Python.

1) Clone & configure

git clone https://github.com/leohux/quantdesk-oss.git
cd quantdesk-oss
cp .env.example .env
# default ADMIN_PASSWORD=changeme1 — change it before any network exposure
# fill ALPACA_* if you want paper trading; leave live locks as-is

What you get out of the box

• Backend: FastAPI (api/)
• Frontend: React + Vite dashboard (web/) — built inside Docker and served by the API
• Not zero-config: copy .env.example → .env (default login password is changeme1; change it). Add Alpaca keys for paper trading.

2) Run with Docker (recommended)

docker compose up -d --build
# UI + API: http://127.0.0.1:18080
# OpenAPI:  http://127.0.0.1:18080/docs
# Login password: value of ADMIN_PASSWORD in .env

Default stack = quantdesk + Postgres + Redis. Optional sidecars use Compose profiles:

docker compose --profile news up -d          # news trader
docker compose --profile mine up -d          # alpha miner
docker compose --profile intraday up -d      # intraday runner
docker compose --profile ibkr up -d          # IB Gateway (credentials required)

IB Gateway is behind a Compose profile and is not started by default.

3) Or run locally

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# another terminal
cd web && npm install && npm run dev

Surface	URL
Frontend (dev)	http://127.0.0.1:5173
API	http://127.0.0.1:8000
OpenAPI	http://127.0.0.1:8000/docs

---

Live Trading (IBKR) — locked by design

IBKR_TRADING_MODE=paper
IBKR_GATEWAY_MODE=paper
IBKR_READ_ONLY=true
LIVE_TRADING_ENABLED=false
LIVE_EXECUTION_ARMED=false

Mode	Submits real orders?
Mock / Shadow	No
IBKR Paper + read-only	No
Live unlocked (all gates)	Yes — only then

Read: docs/LiveTrading.md · SECURITY.md

---

Repository layout

quantdesk/
├── api/                 # FastAPI app
├── core/                # EventBus, strategy, risk, execution, live guard
├── backtest/            # Backtest runners
├── execution/           # Broker helpers (Alpaca paper utilities)
├── strategies/          # Built-in example strategies
├── alpha_miner/         # LLM-assisted alpha proposal loop
├── news_trader/         # News-driven sidecar
├── agents/              # Research / post-mortem agents
├── web/                 # Vite + React + Tailwind dashboard
├── docs/                # Architecture, API, Paper, Live, Deploy
├── deploy/              # Nginx sample + deploy/backup scripts
├── tests/               # Safety & lock tests
├── 打开QuantDesk.bat / start.bat   # double-click to start
├── 关闭QuantDesk.bat / stop.bat    # double-click to stop
├── 使用说明.txt
├── docker-compose.yml
└── .env.example

---

Documentation

Doc	Topic
Architecture	Modules, principles, directory map
Event Flow	EventBus lifecycle
API	REST surface
Paper Trading	Alpaca paper path
Live Trading	IBKR fail-closed path
Deployment	Docker / Nginx

---

Tests

pip install -r requirements.txt
pytest tests/ -q

Run locally with pytest.

---

Roadmap (community-friendly)

• More example strategies + notebook tutorials
• Real product screenshots
• Short demo GIF
• Hardened Docker images (multi-stage, non-root)
• Plugin registry for community strategies
• Optional Prometheus dashboards (sample, no private runbooks)

PRs welcome — see CONTRIBUTING.md.

Community: CODE_OF_CONDUCT.md · CHANGELOG.md · Issues

---

Disclaimer

This project is not a broker, CTA, or investment adviser. Past backtest performance does not imply future results. You are solely responsible for any capital you deploy. Keep live locks engaged until you understand every gate.

---

License

MIT © QuantDesk contributors