Quick start · Repositories · AI agents & MCP · Overview · Features · Visual tour · Architecture · Install · Docs · FAQ · License

QuantDinger is a self-hosted, local-first quantitative platform: AI-assisted research, Python-native strategies, backtesting, and live trading (crypto, IBKR stocks, MT5 forex, Alpaca US stocks/ETFs/crypto) in one product—not a loose collection of scripts and SaaS tabs.

Three steps: clone → set a secret key → docker compose up. On macOS/Linux it's one line. Most of this README is reference — new users don't need to read it to get started.

Prerequisites: Docker with Compose (Docker Desktop on Windows/macOS, or Docker Engine + Compose plugin on Linux), and Git. Node.js is not required (prebuilt UI is in frontend/dist).

git clone https://github.com/brokermr810/QuantDinger.git && cd QuantDinger && cp backend_api_python/env.example backend_api_python/.env && chmod +x scripts/generate-secret-key.sh && ./scripts/generate-secret-key.sh && docker-compose up -d --build

If docker-compose is not found, try docker compose (Compose V2).

git clone https://github.com/brokermr810/QuantDinger.git
Set-Location QuantDinger
Copy-Item backend_api_python\env.example -Destination backend_api_python\.env
$key = & python -c "import secrets; print(secrets.token_hex(32))" 2>$null
if (-not $key) { $key = & py -c "import secrets; print(secrets.token_hex(32))" 2>$null }
if (-not $key) { $key = & python3 -c "import secrets; print(secrets.token_hex(32))" 2>$null }
if (-not $key) { Write-Error "Install Python 3 from python.org (tick 'Add to PATH') or use Git Bash with the macOS/Linux block above." }
(Get-Content backend_api_python\.env) -replace '^SECRET_KEY=.*$', "SECRET_KEY=$key" | Set-Content backend_api_python\.env -Encoding utf8
docker-compose up -d --build

Then open http://localhost:8888, sign in with quantdinger / 123456, and change the default admin password before any real use. That's it — go play.

For deeper configuration, first-run checks, and troubleshooting, see Installation & first-time setup further down (everyone else can skip it).

This monorepo ships the backend, Docker Compose stack, documentation, and a prebuilt web UI under frontend/dist. Use the sibling repos when you need source-level UI changes or the mobile app:

Note: Node.js is only required if you build the web UI from QuantDinger-Vue; the default Docker quick start does not need it.

QuantDinger ships an Agent Gateway at /api/agent/v1 plus a small MCP server (quantdinger-mcp on PyPI) that wraps it as Model Context Protocol tools. Issue a token once and your AI client can read markets, manage strategies, run backtests, and (paper-only by default) place trades — without ever seeing your exchange keys or your admin JWT.

Every agent call is audit-logged, and trading-class tokens are paper-only by default. Live execution requires both paper_only=false on the token AND AGENT_LIVE_TRADING_ENABLED=true on the server.

Two backends, same client config — only QUANTDINGER_BASE_URL differs:

• Hosted (30 s try-out) — sign up at ai.quantdinger.com → Sidebar → Agent Tokens → Issue Token. Locked to paper_only=true, no real-money orders.
• Self-hosted (this repo) — after the Try in 2 minutes Docker bring-up, open http://localhost:8888/#/agent-tokens. You control scopes, allowlists, rate limits, and live-trading flag.

Then point Cursor / Claude Code / Codex at the MCP server (.cursor/mcp.json template: docs/agent/cursor-mcp.example.json):

{ "mcpServers": { "quantdinger": {
  "command": "uvx", "args": ["quantdinger-mcp"],
  "env": { "QUANTDINGER_BASE_URL": "http://localhost:8888",
           "QUANTDINGER_AGENT_TOKEN": "qd_agent_xxxxxxxx" }
} } }

Full setup recipe — local stdio config, remote HTTP transport, Claude Code CLI helper, example agent prompts, audit-log walkthrough: docs/agent/MCP_SETUP.md.

Deeper references: AI Integration design · Quickstart with curl · OpenAPI 3.0 spec · MCP server README

QuantDinger is a self-hosted quantitative OS: AI-assisted research, Python-native strategies (IndicatorStrategy + ScriptStrategy), backtesting, and live trading (crypto, IBKR, MT5, Alpaca)—with optional multi-user roles, notifications, credits, and USDT billing. It replaces a patchwork of charts, notebooks, bots, and disconnected LLM chats with one Compose stack and your credentials in Postgres + .env.

Audience: traders and quants, Python strategy authors, small teams building internal or commercial trading products.

• Research & AI — Multi-LLM analysis, watchlists, analysis history; optional ensemble/calibration; NL→indicator/strategy; post-backtest AI hints. Agent Gateway + MCP for Cursor / Claude Code / Codex.
• Build — IndicatorStrategy (dataframe signals, chart overlays) and ScriptStrategy (on_bar, explicit orders); professional chart UI.
• Validate — Server-side backtests, metrics, equity curves, strategy snapshots.
• Operate — Crypto execution, quick trade, IBKR / MT5 / Alpaca (US stocks, ETFs, crypto), notifications (Telegram, email, SMS, Discord, webhooks). Unified Broker Accounts page centralises connection, account KPIs, positions and open-order management across all brokers.
• Platform — Docker Compose, Postgres, Redis, OAuth, multi-user patterns, credits / membership / USDT billing toggles.

Stack: Nginx serves the prebuilt Vue app (frontend/dist); Flask API runs strategy/AI/billing services; PostgreSQL holds state; Redis backs workers. Exchanges, brokers, LLMs, and payments plug in through env-driven adapters. Crypto market data and order execution paths are separated by design.

Runtime (short): data feeds → backtest/strategy engine → live runtime → exchange adapters; pending orders dispatched per venue.

flowchart LR
    U[Trader / Operator / Researcher]

    subgraph FE[Frontend Layer]
        WEB[Vue Web App]
        NG[Nginx Delivery]
    end

    subgraph BE[Application Layer]
        API[Flask API Gateway]
        AI[AI Analysis Services]
        STRAT[Strategy and Backtest Engine]
        EXEC[Execution and Quick Trade]
        BILL[Billing and Membership]
    end

    subgraph DATA[State Layer]
        PG[(PostgreSQL 16)]
        REDIS[(Redis 7)]
        FILES[Logs and Runtime Data]
    end

    subgraph EXT[External Integrations]
        LLM[LLM Providers]
        EXCH[Crypto Exchanges]
        BROKER[IBKR / MT5 / Alpaca]
        MARKET[Market Data / News]
        PAY[TronGrid / USDT Payment]
        NOTIFY[Telegram / Email / SMS / Webhook]
    end

    U --> WEB
    WEB --> NG --> API
    API --> AI
    API --> STRAT
    API --> EXEC
    API --> BILL

    AI --> PG
    STRAT --> PG
    EXEC --> PG
    BILL --> PG
    API --> REDIS
    API --> FILES

    AI --> LLM
    AI --> MARKET
    EXEC --> EXCH
    EXEC --> BROKER
    BILL --> PAY
    API --> NOTIFY

Already ran Try in 2 minutes? Skip this section — it's the same outcome, just expanded into a step-by-step checklist for first-time deployers and operations folks who want to understand every knob.

This section mirrors a typical “local deploy” path: prepare the host → obtain the code → configure secrets → start the stack → verify → harden → optionally wire AI. Node.js is not required: the repo ships a prebuilt UI under frontend/dist and Nginx serves it inside the frontend container.

git clone https://github.com/brokermr810/QuantDinger.git
cd QuantDinger

cp backend_api_python/env.example backend_api_python/.env

Almost all runtime behavior is driven by backend_api_python/.env (database URL, admin user, LLM keys, workers, billing toggles, etc.). The optional repository root .env only adjusts Compose-level concerns such as ports and image mirrors (IMAGE_PREFIX).

The API refuses to start if SECRET_KEY is still the placeholder from env.example. This blocks accidental insecure deployments.

Linux / macOS (recommended):

./scripts/generate-secret-key.sh

The script overwrites the SECRET_KEY= line in backend_api_python/.env using Python’s secrets module.

Manual (any OS): generate a long random string (for example 64 hex chars) and set SECRET_KEY=... in backend_api_python/.env.

docker-compose up -d --build

Services: postgres, redis, backend, frontend (see docker-compose.yml for healthchecks and port mappings).

If you do not want to clone the repository, the GHCR variant pulls prebuilt multi-arch (amd64/arm64) images for both backend and frontend:

curl -O https://raw.githubusercontent.com/brokermr810/QuantDinger/main/docker-compose.ghcr.yml
curl -o backend.env https://raw.githubusercontent.com/brokermr810/QuantDinger/main/backend_api_python/env.example
docker compose -f docker-compose.ghcr.yml up -d

The backend entrypoint auto-generates a random SECRET_KEY on first start and applies the schema (migrations/init.sql) idempotently. Edit backend.env for persistent overrides (API keys, OAuth, broker credentials). Compose orchestration knobs go in a separate .env (optional) — e.g. pin a version:

IMAGE_TAG=v3.0.7
# BACKEND_IMAGE=ghcr.io/<your-fork>/quantdinger-backend     # optional, for forks
# FRONTEND_IMAGE=ghcr.io/<your-fork>/quantdinger-frontend

Defaults: ghcr.io/brokermr810/quantdinger-backend:latest + ghcr.io/brokermr810/quantdinger-frontend:latest.

Default admin (change immediately in production):

• User: quantdinger
• Password: 123456 (from env.example; override with ADMIN_USER / ADMIN_PASSWORD in .env before first use if you prefer).

Also set FRONTEND_URL in backend_api_python/.env to the URL users actually use (including https:// behind a reverse proxy); it affects redirects, CORS-related settings, and some generated links.

AI analysis, NL→code, and related flows need at least one LLM provider configured. Open backend_api_python/env.example, find the AI / LLM block, copy the relevant keys into your .env (for example LLM_PROVIDER + OPENROUTER_API_KEY, or another supported provider). Restart the backend after edits.

Use Docker Desktop (WSL2 backend recommended). From PowerShell in the repo root:

git clone https://github.com/brokermr810/QuantDinger.git
cd QuantDinger
Copy-Item backend_api_python\env.example -Destination backend_api_python\.env
$key = py -c "import secrets; print(secrets.token_hex(32))"
(Get-Content backend_api_python\.env) -replace '^SECRET_KEY=.*$', "SECRET_KEY=$key" | Set-Content backend_api_python\.env -Encoding UTF8
docker-compose up -d --build

If py is not on PATH, use python or python3 in the one-liner that generates $key. Line endings should remain UTF-8; avoid editors that strip newlines from .env.

docker-compose ps
docker-compose logs -f backend
docker-compose restart backend
docker-compose up -d --build
docker-compose down

For custom ports or mirror/prefix for base images (slow Docker Hub pulls), create a file named .env in the repository root (same directory as docker-compose.yml):

FRONTEND_PORT=3000
BACKEND_PORT=127.0.0.1:5001
IMAGE_PREFIX=docker.m.daocloud.io/library/

Production-style TLS, domain, and reverse-proxy placement are covered in Cloud deployment.

After the stack is healthy: (1) run an AI asset / market analysis so LLM and data paths are verified; (2) open the Indicator IDE, load a symbol, and run a signal backtest on a small date range; (3) optionally use AI code generation to draft an indicator, then edit the Python; (4) when ready, attach exchange API keys (profile / credentials), use test connection, then explore live strategy or quick trade with execution mode you intend. This order surfaces configuration issues early before real capital.

This is the kind of Python-native strategy logic QuantDinger is designed for:

# @param sma_short int 14 Short moving average
# @param sma_long int 28 Long moving average

sma_short_period = params.get('sma_short', 14)
sma_long_period = params.get('sma_long', 28)

my_indicator_name = "Dual Moving Average Strategy"
my_indicator_description = f"SMA {sma_short_period}/{sma_long_period} crossover"

df = df.copy()
sma_short = df["close"].rolling(sma_short_period).mean()
sma_long = df["close"].rolling(sma_long_period).mean()

buy = (sma_short > sma_long) & (sma_short.shift(1) <= sma_long.shift(1))
sell = (sma_short < sma_long) & (sma_short.shift(1) >= sma_long.shift(1))

df["buy"] = buy.fillna(False).astype(bool)
df["sell"] = sell.fillna(False).astype(bool)

See full examples:

• docs/examples/dual_ma_with_params.py
• docs/examples/multi_indicator_composite.py
• docs/examples/cross_sectional_momentum_rsi.py

Broker Accounts page (/broker-accounts, v3.0.5+) — IBKR, MT5 and Alpaca share a single unified management page: per-broker connect form, account KPIs, positions table and open-order management with one-click cancel. Multi-tenant safe: each user's session is isolated via BrokerSessionRegistry, so one user reconnecting doesn't kick everyone else off.

QuantDinger supports two main strategy authoring models:

• dataframe-based Python scripts
• buy / sell signal generation
• chart rendering and signal-style backtests
• best for research, indicator logic, and visual strategy prototyping

• event-driven on_init(ctx) / on_bar(ctx, bar) scripts
• explicit runtime control with ctx.buy(), ctx.sell(), ctx.close_position()
• best for stateful strategies, execution-oriented logic, and live alignment

For the full developer workflow, see:

• Strategy Development Guide
• Cross-Sectional Strategy Guide
• Strategy Examples

The example scripts live in docs/examples/ and are kept aligned with the current strategy development guides.

QuantDinger/
├── backend_api_python/      # Open backend source code
│   ├── app/routes/          # REST endpoints
│   ├── app/services/        # AI, trading, billing, backtest, integrations
│   ├── migrations/init.sql  # Database initialization
│   ├── env.example          # Main environment template
│   └── Dockerfile
├── frontend/                # Prebuilt web UI (sources: QuantDinger-Vue; mobile app: QuantDinger-Mobile)
│   ├── dist/
│   ├── Dockerfile
│   └── nginx.conf
├── docs/                    # Product, strategy, and deployment documentation
├── docker-compose.yml
├── LICENSE
└── TRADEMARKS.md

Use backend_api_python/env.example as the primary template. Key areas include:

Strategy: EN · CN · TW · JA · KO · Cross-sectional EN / CN · Examples

Integrations & alerts: IBKR · MT5 EN / CN · OAuth EN / CN · Telegram / Email / SMS configs under docs/ (NOTIFICATION_*).

Yes. The default deployment model is your own Docker Compose stack with your own database, Redis instance, credentials, and environment configuration.

No. Crypto is a major focus, but the platform also includes IBKR and Alpaca workflows for US stocks / ETFs (Alpaca additionally covers crypto) and MT5 workflows for forex.

Yes. QuantDinger supports both dataframe-style IndicatorStrategy development and event-driven ScriptStrategy development. You can also use AI to generate a starting point and then edit it yourself.

It is both. QuantDinger is built to connect AI research, charting, strategy development, backtesting, quick trade flows, and live execution operations in one system.

The backend is licensed under Apache 2.0. The web frontend source (QuantDinger-Vue) uses a separate source-available license—review both and contact the project for commercial frontend authorization if needed. The mobile app repo is open source under its own license (see that repository).

Yes—see QuantDinger-Mobile (open source). It connects to the same backend you self-host or to SaaS.

The following links are available in-app under Profile -> Open account and may qualify users for trading-fee rebates depending on venue policies.

• Backend source code is licensed under Apache License 2.0. See LICENSE.
• This repository distributes the frontend UI here as prebuilt files for integrated deployment.
• The frontend source code is available separately at QuantDinger Frontend under the QuantDinger Frontend Source-Available License v1.0.
• Under that frontend license, non-commercial use and eligible qualified non-profit use are permitted free of charge, while commercial use requires a separate commercial license from the copyright holder.
• Trademark, branding, attribution, and watermark usage are governed separately and may not be removed or altered without permission. See TRADEMARKS.md.

For commercial licensing, frontend source access, branding authorization, or deployment support:

• Website: quantdinger.com
• Telegram: t.me/worldinbroker
• Email: support@quantdinger.com

QuantDinger is intended for lawful research, education, and compliant trading only—not for fraud, market manipulation, sanctions evasion, money laundering, or other illegal activity. Operators must follow applicable laws, licensing, and exchange rules in every jurisdiction where they deploy. This project does not provide legal, tax, investment, or regulatory advice. You use the software at your own risk; to the extent permitted by law, contributors disclaim liability for trading losses, service interruption, or regulatory enforcement arising from use or misuse.

• Contributing Guide
• Contributors
• Report Bugs / Request Features
• Email: support@quantdinger.com

Crypto donations:

0x96fa4962181bea077f8c7240efe46afbe73641a7

QuantDinger stands on top of a strong open-source ecosystem. Special thanks to projects such as:

• Flask
• Pandas
• CCXT
• yfinance
• Vue.js
• Ant Design Vue
• KLineCharts
• ECharts
• Capacitor
• bip-utils

_{If QuantDinger is useful to you, a GitHub star helps the project a lot.}