---

Contents

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) in one product—not a loose collection of scripts and SaaS tabs.

Try in 2 minutes

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

macOS / Linux (Bash)

One line (or run the same steps separately):

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 ./scripts/generate-secret-key.sh fails with “Permission denied”, run chmod +x scripts/generate-secret-key.sh and retry. If docker-compose is not found, try docker compose (Compose V2).

Windows (PowerShell)

Use PowerShell (not CMD) in a folder where you want the project. Docker Desktop must be running (WSL2 backend recommended).

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

If docker-compose is not recognized, use docker compose (space, no hyphen). If Git is missing, install Git for Windows.

Windows alternative: Git Bash

If you installed Git for Windows, open Git Bash and you can use the macOS / Linux one-liner above (Bash + chmod + ./scripts/generate-secret-key.sh).

---

Then open http://localhost:8888, sign in with quantdinger / 123456, and change the default admin password before any real use. For prerequisites, configuration details, first-run checks, and troubleshooting, continue to Installation & first-time setup below.

Related repositories

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:

Repository	What it is
QuantDinger (this repo)	Backend (Flask/Python), deployment, docs, bundled web assets
QuantDinger-Vue	Web frontend source (Vue)—themes, forks, npm run build → replace frontend/dist
QuantDinger-Mobile	Open-source mobile client—pairs with your self-hosted or SaaS backend

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

Use it from an AI agent (Cursor / Claude Code / Codex / MCP)

QuantDinger ships an Agent Gateway at /api/agent/v1 and a small MCP server that wraps it as Model Context Protocol tools. Once you sign in once and issue a token, 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.

Two safety properties are non-negotiable: 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.

Step 1 — Get an agent token (two paths, your choice)

The MCP client and the wiring in Step 2 are identical for both paths — only the value of QUANTDINGER_BASE_URL changes.

Path A · Hosted (ai.quantdinger.com) — try it in 30 seconds. Sign up → open Sidebar → Agent Tokens → Issue Token. The hosted instance is locked to paper_only=true and the T (Trading) scope is rejected at issuance — agents can read markets, manage strategies in your tenant, and run backtests, but never route real-money orders. Set QUANTDINGER_BASE_URL=https://ai.quantdinger.com. Best for: trying QuantDinger from Cursor / Claude Code without installing anything; demos; research notebooks against shared datasets.

Path B · Self-hosted (this repo) — production / private data / live trading. After the Try in 2 minutes Docker bring-up, log in as admin and open Sidebar → Agent Tokens (or http://localhost:8888/#/agent-tokens). You decide scopes (incl. T), market/instrument allowlists, rate limits, and whether AGENT_LIVE_TRADING_ENABLED=true is ever flipped. Set QUANTDINGER_BASE_URL=http://localhost:8888 (or your LAN URL). Best for: anyone with their own exchange keys, anyone with private strategies/data, teams behind a VPN, or anyone who eventually wants live execution.

In either path:

1. Click Issue Token → name it (cursor-mcp, claude-research, …).
2. Pick scopes — start with R + B (read + backtest); add W to let the agent create/edit strategies.
3. Copy the token once — the dialog shows the full string once; the server only keeps a SHA-256 hash.

Prefer the CLI? See docs/agent/AGENT_QUICKSTART.md for the equivalent curl.

Step 2 — Wire the MCP server into your AI client

The MCP server lives in mcp_server/. Two transports work everywhere:

A. Local stdio (Cursor, Claude Code, Codex desktop, etc.) — the server is published on PyPI as quantdinger-mcp. Drop this into .cursor/mcp.json, ~/.config/claude/claude_desktop_config.json, or your client's equivalent (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"
      }
    }
  }
}

uvx (install uv) downloads + caches the package on first run; no virtualenv setup. If you prefer pip:

pip install quantdinger-mcp
# then use {"command": "quantdinger-mcp", "args": []}

For Claude Code's CLI helper:

claude mcp add quantdinger \
  --env QUANTDINGER_BASE_URL=http://localhost:8888 \
  --env QUANTDINGER_AGENT_TOKEN=qd_agent_xxxxxxxx \
  -- uvx quantdinger-mcp

B. Remote HTTP (cloud agents like OpenClaw / NanoBot, browser IDEs, anything that can't spawn subprocesses) — run the MCP server as a long-lived service, then point clients at the URL:

QUANTDINGER_BASE_URL=https://your-host \
QUANTDINGER_AGENT_TOKEN=qd_agent_xxxxxxxx \
QUANTDINGER_MCP_TRANSPORT=streamable-http \
QUANTDINGER_MCP_HOST=0.0.0.0 \
QUANTDINGER_MCP_PORT=7800 \
quantdinger-mcp
# clients connect to http://your-host:7800

Use QUANTDINGER_MCP_TRANSPORT=sse instead for clients that only speak the older SSE transport. Put a reverse proxy in front for TLS and IP allowlisting.

Step 3 — Talk to your agent

Restart the IDE, then ask things like:

• "Pull the last 90 daily candles for BTC/USDT and tell me what the regime detector says."
• "Backtest the 20/60 SMA crossover on ETH/USDT 4h between 2024-01-01 and 2024-06-30 and stream the result as it runs."
• "Create a strategy named eth-trend-bot, use the indicator I just designed, leave it in stopped state."

Long-running jobs (/api/agent/v1/jobs/{id}/stream) are exposed as SSE so the agent can react to partial results without polling. Every call shows up under Agent Tokens → Audit log with route, scope class, status code, and duration.

Want to use QuantDinger as a coding agent context too?

If you're editing this repo with Cursor / Claude Code / Codex, the repo also ships a Cursor Skill at .cursor/skills/quantdinger-agent-workflow/SKILL.md that explains the Agent Gateway internals, red lines (no real keys, paper-only by default), and where to verify changes. Read docs/agent/AGENT_ENVIRONMENT_DESIGN.md for the full layered-contracts model.

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

Product overview

QuantDinger is a self-hosted quantitative OS: AI-assisted research, Python-native strategies (IndicatorStrategy + ScriptStrategy), backtesting, and live trading (crypto, IBKR, MT5)—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.

Typical DIY stack	QuantDinger
Chat AI separate from execution	Analysis, NL→code, backtests, and execution in one product
Many tools wired by hand	Nginx + Vue UI, Flask API, workers, exchange/LLM adapters
Opaque SaaS keys	Your infra, your exchange keys, your LLM keys

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

Visual Tour

▶ Watch Product Demo on YouTube Click the preview card above to open the full video walkthrough.
Indicator IDE, charting, backtest, and quick trade	AI asset analysis and opportunity radar
Trading bot workspace and automation templates	Strategy live operations, performance, and monitoring

Features at a glance

• Research & AI — Multi-LLM analysis, watchlists, analysis history; optional ensemble/calibration; NL→indicator/strategy; post-backtest AI hints; Polymarket as a research workflow. 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, notifications (Telegram, email, SMS, Discord, webhooks).
• Platform — Docker Compose, Postgres, Redis, OAuth, multi-user patterns, credits / membership / USDT billing toggles.

Architecture

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.

System diagram

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]
        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

Installation & first-time setup (Docker Compose)

Fast path: Try in 2 minutes first. The steps below are the full checklist (same outcome, more detail).

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.

Prerequisites

Item	Notes
Docker + Docker Compose v2	Used for Postgres, Redis, API, and static UI.
git	To clone this repository.
Ports (defaults)	8888 (web), 5000 (API, bound to 127.0.0.1), 5432 / 6379 (DB/Redis, loopback by default). Change via root .env if they collide.
Disk	Postgres volume grows with users, strategies, and logs; plan a few GB minimum for serious use.

1) Clone the repository

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

2) Create backend configuration (mandatory)

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

3) Set SECRET_KEY before the first boot (mandatory)

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.

4) Start the stack

docker-compose up -d --build

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

5) Verify and sign in

Check	URL / command
Web UI	http://localhost:8888 (override host/port with FRONTEND_HOST / FRONTEND_PORT in root .env if needed).
API health	http://localhost:5000/api/health
Logs	docker-compose logs -f backend

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.

6) Optional: enable AI features

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.

7) Windows notes

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.

Troubleshooting (first boot)

Symptom	What to check
Backend exits immediately	SECRET_KEY still default, or invalid .env syntax. Read docker-compose logs backend.
Blank page or API errors from browser	FRONTEND_URL / origins mismatch; API not reachable from the host you opened.
Port already in use	Another Postgres, Redis, or local service on 5432 / 6379 / 5000 / 8888. Adjust variables in root .env per docker-compose.yml.
Many live strategies, “start denied”	Raise STRATEGY_MAX_THREADS in backend_api_python/.env and restart API (see comments in env.example).

Common Docker commands

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

Optional root .env (Compose only)

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.

Suggested first session (product walkthrough)

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.

Minimal Example: Python Indicator Strategy

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

Supported Markets, Brokers, and Exchanges

Crypto Exchanges

Venue	Coverage
Binance	Spot, Futures, Margin
OKX	Spot, Perpetual, Options
Bitget	Spot, Futures, Copy Trading
Bybit	Spot, Linear Futures
Coinbase	Spot
Kraken	Spot, Futures
KuCoin	Spot, Futures
Gate.io	Spot, Futures
Deepcoin	Derivatives integration
HTX	Spot, USDT-margined perpetuals

Traditional Markets

Market	Broker / Source	Execution
US Stocks	IBKR, Yahoo Finance, Finnhub	Via IBKR
Forex	MT5, OANDA	Via MT5
Futures	Exchange and data integrations	Data and workflow support

Prediction Markets

Polymarket is currently supported as a research and analysis workflow, not as direct in-platform live execution. It is useful for market lookup, divergence analysis, opportunity scoring, and AI-assisted review.

Strategy Development Modes

QuantDinger supports two main strategy authoring models:

IndicatorStrategy

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

ScriptStrategy

• 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.

Repository Layout

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

Configuration Areas

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

Area	Examples
Authentication	SECRET_KEY, ADMIN_USER, ADMIN_PASSWORD
Database	DATABASE_URL
LLM / AI	LLM_PROVIDER, OPENROUTER_API_KEY, OPENAI_API_KEY
OAuth	GOOGLE_CLIENT_ID, GITHUB_CLIENT_ID
Security	TURNSTILE_SITE_KEY, ENABLE_REGISTRATION
Billing	BILLING_ENABLED, BILLING_COST_AI_ANALYSIS
Membership	MEMBERSHIP_MONTHLY_PRICE_USD, MEMBERSHIP_MONTHLY_CREDITS
USDT Payment	USDT_PAY_ENABLED, USDT_TRC20_XPUB, TRONGRID_API_KEY
Optional data APIs	TWELVE_DATA_API_KEY, FINNHUB_API_KEY, TIINGO_API_KEY, ADANOS_API_KEY
Proxy	PROXY_URL
Workers	ENABLE_PENDING_ORDER_WORKER, ENABLE_PORTFOLIO_MONITOR, ENABLE_REFLECTION_WORKER
AI tuning	ENABLE_AI_ENSEMBLE, ENABLE_CONFIDENCE_CALIBRATION, AI_ENSEMBLE_MODELS

Documentation

Doc	Notes
Changelog	Releases & migrations
README (中文)	Chinese overview
JA · KO · TH · VI · AR	Concise localized READMEs (Japanese, Korean, Thai, Vietnamese, Arabic)
Cloud deployment	HTTPS, reverse proxy, production
Multi-user	Postgres multi-tenant patterns
Agent environment · AI integration · Quickstart · OpenAPI · MCP server	Coding agents & MCP (quantdinger-mcp on PyPI)

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_*).

FAQ

Is QuantDinger really self-hosted?

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

Is QuantDinger only for crypto trading?

No. Crypto is a major focus, but the platform also includes IBKR workflows for US stocks, MT5 workflows for forex, and Polymarket research support.

Can I write strategies directly in Python?

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.

Is this a research tool or a live trading platform?

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

Can I use QuantDinger commercially?

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

Is there a mobile app?

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

Exchange Partner Links

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

Exchange	Signup Link
Binance	Register
Bitget	Register
Bybit	Register
OKX	Register
Gate.io	Register
HTX	Register

License and Commercial Terms

• 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

Legal Notice and Compliance

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.

Community and Support

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

Support the Project

Crypto donations:

0x96fa4962181bea077f8c7240efe46afbe73641a7

Star History

Acknowledgements

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.}