---
## ๐ Introduction
**QuantDinger** is a **Local-First** quantitative trading workspace designed for traders, researchers, and geeks.
Unlike expensive SaaS platforms, QuantDinger returns **data ownership** to you. It features a built-in **LLM-based Multi-Agent Research Team** that autonomously gathers financial intelligence from the web, combines it with local market data, generates professional analysis reports, and seamlessly integrates with your strategy development, backtesting, and live trading workflows.
### Core Value
- **๐ก๏ธ Privacy First**: All strategies, trading logs, and API keys are stored locally in your SQLite database.
- **๐ง AI Empowered**: Not just code completion, but a real AI Research Analyst (powered by OpenRouter/LLM).
- **โก Multi-Market**: Native support for **Crypto**, **US Stocks**, **CN/HK Stocks**, **Forex**, and **Futures**.
- **๐ Out-of-the-Box**: One-click deployment via Docker. No complex environment setup required.
---
## ๐ Documentation
- [Python Strategy Development Guide](docs/STRATEGY_DEV_GUIDE.md)
## ๐ธ Visual Tour
๐ Professional Quant Dashboard
Real-time monitoring of market dynamics, assets, and strategy status.
๐ค AI Deep Research
Multi-agent collaboration for market sentiment & technical analysis.
|
๐ฌ Smart Trading Assistant
Natural language interface for instant market insights.
|
๐ Interactive Indicator Analysis
Rich library of technical indicators with drag-and-drop analysis.
|
๐ Python Strategy Gen
Built-in editor with AI-assisted strategy coding.
|
---
## โจ Key Features
### 1. Universal Data Engine
Stop worrying about data APIs. QuantDinger features a powerful Data Source Factory pattern:
- **Crypto**: **Direct API connection** for trading (10+ exchanges) combined with **CCXT** for market data (100+ sources).
- **Stocks**: Integrates Yahoo Finance, Finnhub, Tiingo (US), and AkShare (CN/HK).
- **Futures/Forex**: Supports OANDA and major futures data sources.
- **Proxy Support**: Built-in proxy configuration for restricted network environments.
### 2. AI Multi-Agent Research
Your tireless team of analysts:
- **Coordinator Agent**: Decomposes tasks and manages workflows.
- **Research Agent**: Performs full-web searches (Google/Bing) for macro news.
- **Crypto/Stock Agent**: Specializes in technical and capital flow analysis for specific markets.
- **Report Generation**: Automatically produces structured Daily/Weekly research reports.
### 2.1 ๐ง Memory-Augmented Agents (Local RAG + Reflection Loop)
QuantDingerโs agents donโt start from scratch every time. The backend includes a **local memory store** and an optional **reflection/verification loop**:
- **What it is**: RAG-style experience retrieval injected into agent prompts (NOT model fine-tuning).
- **Where it lives**: Local SQLite files under `backend_api_python/data/memory/` (privacy-first).
```mermaid
flowchart TB
%% ===== ๐ Entry Layer =====
subgraph Entry["๐ API Entry"]
A["๐ก POST /api/analysis/multi"]
A2["๐ POST /api/analysis/reflect"]
end
%% ===== โ๏ธ Service Layer =====
subgraph Service["โ๏ธ Service Orchestration"]
B[AnalysisService]
C[AgentCoordinator]
D["๐ Build Context
price ยท kline ยท news ยท indicators"]
end
%% ===== ๐ค Multi-Agent Workflow =====
subgraph Agents["๐ค Multi-Agent Workflow"]
subgraph P1["๐ Phase 1 ยท Analysis (Parallel)"]
E1["๐ MarketAnalyst
Technical"]
E2["๐ FundamentalAnalyst
Fundamentals"]
E3["๐ฐ NewsAnalyst
News & Events"]
E4["๐ญ SentimentAnalyst
Market Mood"]
E5["โ ๏ธ RiskAnalyst
Risk Assessment"]
end
subgraph P2["๐ฏ Phase 2 ยท Debate (Parallel)"]
F1["๐ BullResearcher
Bullish Case"]
F2["๐ป BearResearcher
Bearish Case"]
end
subgraph P3["๐น Phase 3 ยท Decision"]
G["๐ฐ TraderAgent
Final Verdict โ BUY / SELL / HOLD"]
end
end
%% ===== ๐ง Memory Layer =====
subgraph Memory["๐ง Local SQLite Memory (data/memory/)"]
M1[("market_analyst")]
M2[("fundamental")]
M3[("news_analyst")]
M4[("sentiment")]
M5[("risk_analyst")]
M6[("bull_researcher")]
M7[("bear_researcher")]
M8[("trader_agent")]
end
%% ===== ๐ Reflection Loop =====
subgraph Reflect["๐ Reflection Loop (Optional)"]
R[ReflectionService]
RR[("reflection_records.db")]
W["โฐ ReflectionWorker"]
end
%% ===== Main Flow =====
A --> B --> C --> D
D --> P1 --> P2 --> P3
%% ===== Memory Read/Write =====
E1 <-.-> M1
E2 <-.-> M2
E3 <-.-> M3
E4 <-.-> M4
E5 <-.-> M5
F1 <-.-> M6
F2 <-.-> M7
G <-.-> M8
%% ===== Reflection Flow =====
C --> R --> RR
W --> RR
W -.->|"verify + learn"| M8
A2 -.->|"manual review"| M8
```
**Retrieval ranking (simplified)**:
\[
score = w_{sim}\cdot sim + w_{recency}\cdot recency + w_{returns}\cdot returns\_score
\]
Config lives in `.env` (see `backend_api_python/env.example`): `ENABLE_AGENT_MEMORY`, `AGENT_MEMORY_TOP_K`, `AGENT_MEMORY_ENABLE_VECTOR`, `AGENT_MEMORY_HALF_LIFE_DAYS`, and `ENABLE_REFLECTION_WORKER`.
### 3. Robust Strategy Runtime
- **Thread-Based Executor**: Independent thread pool management for strategy execution.
- **Auto-Restore**: Automatically resumes running strategies after system restarts.
- **Pending Order Worker**: Reliable background queue ensures precise signal execution and prevents slippage.
### 4. Modern Tech Stack
- **Backend**: Python (Flask) + SQLite + Redis (Optional) โ Simple, powerful, extensible.
- **Frontend**: Vue 2 + Ant Design Vue + KlineCharts/ECharts โ Responsive and interactive.
- **Deployment**: Docker Compose orchestration.
---
## ๐ฆ Supported Exchanges & Rebates
QuantDinger supports **direct connection** to major cryptocurrency exchanges for low-latency execution, while using **CCXT** for broad market data coverage.
> ๐ก **Exclusive Benefits**: Create accounts through our partner links below to enjoy **reduced trading fees** and **exclusive bonuses**. It helps support the project at no extra cost to you!
| Exchange | Features | Sign Up Bonus |
|:--------:|:---------|:-------------:|
| 
| ๐ฅ **World's Largest**
Spot, Futures, Margin | 
|
| 
| ๐ **Web3 & Derivatives**
Spot, Perpetual, Options | 
|
| 
| ๐ฅ **Social Trading**
Copy Trading, Futures | 
|
**Also Supported (Direct/CCXT):**
| 
| 
| 
| 
| 
|
|:---:|:---:|:---:|:---:|:---:|
---
### Multi-Language Support
QuantDinger is built for a global audience with comprehensive internationalization:
All UI elements, error messages, and documentation are fully translated. Language is auto-detected based on browser settings or can be manually switched in the app.
---
### Supported Markets
| Market Type | Data Sources | Trading |
|-------------|--------------|---------|
| **Cryptocurrency** | Binance, OKX, Bitget, + 100 exchanges | โ
Full support |
| **US Stocks** | Yahoo Finance, Finnhub, Tiingo | โ
Via broker API |
| **CN/HK Stocks** | AkShare, East Money | โก Data only |
| **Forex** | Finnhub, OANDA | โ
Via broker API |
| **Futures** | Exchange APIs, AkShare | โก Data only |
---
### Architecture (Current Repo)
```text
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ quantdinger_vue โ
โ (Vue 2 + Ant Design Vue) โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโ
โ HTTP (/api/*)
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ backend_api_python โ
โ (Flask + strategy runtime) โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโ
โ
โโ SQLite (quantdinger.db)
โโ Redis (optional cache)
โโ Data providers / LLMs / Exchanges
```
---
### Repository Layout
```text
.
โโ backend_api_python/ # Flask API + AI + backtest + strategy runtime
โ โโ app/
โ โโ env.example # Copy to .env for local config
โ โโ requirements.txt
โ โโ run.py # Entrypoint
โโ quantdinger_vue/ # Vue 2 UI (dev server proxies /api -> backend)
```
---
## Quick Start
### Option 1: Docker Deployment (Recommended)
The fastest way to get QuantDinger running.
#### 1. Start Services
**Linux / macOS**
```bash
git clone https://github.com/brokermr810/QuantDinger.git && \
cd QuantDinger && \
cp backend_api_python/env.example backend_api_python/.env && \
docker-compose up -d --build
```
**Windows (PowerShell)**
```powershell
git clone https://github.com/brokermr810/QuantDinger.git
cd QuantDinger
Copy-Item backend_api_python\env.example -Destination backend_api_python\.env
docker-compose up -d --build
```
#### 2. Configuration & Access
- **Frontend UI**: http://localhost:8888
- **Default Account**: `quantdinger` / `123456`
> **Note**: For production or AI features, edit `backend_api_python/.env` (add `OPENROUTER_API_KEY`, change passwords) and restart with `docker-compose restart backend`.
#### 3. Access the Application
- **Frontend UI**: http://localhost
- **Backend API**: http://localhost:5000
#### Docker Commands Reference
```bash
# View running status
docker-compose ps
# View logs
docker-compose logs -f
# View backend logs only
docker-compose logs -f backend
# View frontend logs only
docker-compose logs -f frontend
# Stop services
docker-compose down
# Stop and remove volumes (WARNING: deletes database!)
docker-compose down -v
# Restart services
docker-compose restart
# Rebuild and restart
docker-compose up -d --build
# Enter backend container
docker exec -it quantdinger-backend /bin/bash
# Enter frontend container
docker exec -it quantdinger-frontend /bin/sh
```
#### Docker Architecture
```
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Frontend โ โ Backend โ
โ (Nginx) โโโโโโถโ (Python) โ
โ Port: 80 โ โ Port: 5000 โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโ
Docker Network
```
- **Frontend**: Vue.js app served by Nginx, proxies API requests to backend
- **Backend**: Python Flask API service
#### Data Persistence
The following data is mounted to the host and persists across container restarts:
```yaml
volumes:
- ./backend_api_python/quantdinger.db:/app/quantdinger.db # Database
- ./backend_api_python/logs:/app/logs # Logs
- ./backend_api_python/data:/app/data # Data directory
- ./backend_api_python/.env:/app/.env # Configuration
```
#### Customization
**Change ports** - Edit `docker-compose.yml`:
```yaml
services:
frontend:
ports:
- "8080:80" # Change to port 8080
backend:
ports:
- "5001:5000" # Change to port 5001
```
**Configure HTTPS** - Use a reverse proxy (like Caddy/Nginx):
```bash
# Using Caddy (automatic HTTPS)
caddy reverse-proxy --from yourdomain.com --to localhost:80
```
#### Production Recommendations
**Security:**
```bash
# Generate strong SECRET_KEY
openssl rand -hex 32
# Set secure admin password
ADMIN_PASSWORD=your-very-secure-password
```
**Resource limits** - Add to `docker-compose.yml`:
```yaml
services:
backend:
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '0.5'
memory: 512M
```
**Log management:**
```yaml
services:
backend:
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "3"
```
#### Docker Troubleshooting
**Frontend can't connect to backend:**
```bash
docker-compose logs backend
curl http://localhost:5000/api/health
```
**Database permission issues:**
```bash
chmod 666 backend_api_python/quantdinger.db
```
**Build failures:**
```bash
# Clear Docker cache and rebuild
docker-compose build --no-cache
```
**Out of memory:**
```bash
# Check memory usage
docker stats
# Add swap space (Linux)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
#### Updating
```bash
# Pull latest code
git pull
# Rebuild and restart
docker-compose up -d --build
```
#### Backup
```bash
# Backup database
cp backend_api_python/quantdinger.db backup/quantdinger_$(date +%Y%m%d).db
# Backup configuration
cp backend_api_python/.env backup/.env_$(date +%Y%m%d)
```
---
### Option 2: Local Development
**Prerequisites**
- Python 3.10+ recommended
- Node.js 16+ recommended
#### 1. Start the backend (Flask API)
```bash
cd backend_api_python
pip install -r requirements.txt
cp env.example .env # Windows: copy env.example .env
python run.py
```
Backend will be available at `http://localhost:5000`.
#### 2. Start the frontend (Vue UI)
```bash
cd quantdinger_vue
npm install
npm run serve
```
Frontend dev server runs at `http://localhost:8000` and proxies `/api/*` to `http://localhost:5000` (see `quantdinger_vue/vue.config.js`).
---
### Configuration (.env)
Use `backend_api_python/env.example` as a template. Common settings include:
- **Auth**: `SECRET_KEY`, `ADMIN_USER`, `ADMIN_PASSWORD`
- **Server**: `PYTHON_API_HOST`, `PYTHON_API_PORT`, `PYTHON_API_DEBUG`
- **Database**: `SQLITE_DATABASE_FILE` (optional; default is `backend_api_python/data/quantdinger.db`)
- **AI / LLM**: `OPENROUTER_API_KEY`, `OPENROUTER_MODEL`, timeouts
- **Web search**: `SEARCH_PROVIDER`, `SEARCH_GOOGLE_*`, `SEARCH_BING_API_KEY`
- **Proxy (optional)**: `PROXY_PORT` or `PROXY_URL`
- **Workers**: `ENABLE_PENDING_ORDER_WORKER`, `DISABLE_RESTORE_RUNNING_STRATEGIES`
---
### API
The backend provides REST endpoints for login, market data, indicators, backtesting, strategies, and AI analysis.
- Health: `GET /health` (also supports `GET /api/health` for deployment probes)
- Auth (frontend-compatible): `POST /api/user/login`, `POST /api/user/logout`, `GET /api/user/info`
For the full route list, see `backend_api_python/app/routes/`.
---
### License
Licensed under the **Apache License 2.0**. See `LICENSE`.
---
## ๐ค Community & Support
Join our global community for strategy sharing and technical support:
- **Telegram (Group)**: [Join QuantDinger Telegram Group](https://t.me/+ULKYtlLEE9M4ZWZl)
- **Discord**: [Join Server](https://discord.gg/cn6HVE2KC)
- **YouTube**: [@quantdinger](https://youtube.com/@quantdinger)
- **Email**: [brokermr810@gmail.com](mailto:brokermr810@gmail.com)
- **GitHub Issues**: [Report bugs / Request features](https://github.com/brokermr810/QuantDinger/issues)
---
## โ Support the Project
If QuantDinger helps you profit, consider buying the developers a coffee. Your support keeps the project alive!
**ERC-20 / BEP-20 / Polygon / Arbitrum**
```
0x96fa4962181bea077f8c7240efe46afbe73641a7
```
---
### Commercial Services
We offer professional services to help you get the most out of QuantDinger:
| Service | Description |
|---------|-------------|
| **Deployment & Setup** | One-on-one assistance with server deployment, configuration, and optimization |
| **Custom Strategy Development** | Tailored trading strategies designed for your specific needs and markets |
| **Enterprise Upgrade** | Commercial license, priority support, and advanced features for businesses |
| **Training & Consulting** | Hands-on training sessions and strategic consulting for your trading team |
**Interested?** Contact us via:
- ๐ง Email: [brokermr810@gmail.com](mailto:brokermr810@gmail.com)
- ๐ฌ Telegram: [QuantDinger Group](https://t.me/+ULKYtlLEE9M4ZWZl)
---
### Acknowledgements
QuantDinger stands on the shoulders of great open-source projects:
| Project | Description | Link |
|---------|-------------|------|
| **Flask** | Lightweight WSGI web framework | [flask.palletsprojects.com](https://flask.palletsprojects.com/) |
| **flask-cors** | Cross-Origin Resource Sharing extension | [GitHub](https://github.com/corydolphin/flask-cors) |
| **Pandas** | Data analysis and manipulation library | [pandas.pydata.org](https://pandas.pydata.org/) |
| **CCXT** | Cryptocurrency exchange trading library | [github.com/ccxt/ccxt](https://github.com/ccxt/ccxt) |
| **yfinance** | Yahoo Finance market data downloader | [github.com/ranaroussi/yfinance](https://github.com/ranaroussi/yfinance) |
| **akshare** | China financial data interface | [github.com/akfamily/akshare](https://github.com/akfamily/akshare) |
| **requests** | HTTP library for Python | [requests.readthedocs.io](https://requests.readthedocs.io/) |
| **Vue.js** | Progressive JavaScript framework | [vuejs.org](https://vuejs.org/) |
| **Ant Design Vue** | Enterprise-class UI components | [antdv.com](https://antdv.com/) |
| **KlineCharts** | Lightweight financial charting library | [github.com/klinecharts/KLineChart](https://github.com/klinecharts/KLineChart) |
| **Lightweight Charts** | TradingView charting library | [github.com/nicepkg/lightweight-charts](https://github.com/nicepkg/lightweight-charts) |
| **ECharts** | Apache data visualization library | [echarts.apache.org](https://echarts.apache.org/) |
Thanks to all maintainers and contributors across these ecosystems! โค๏ธ
