Supports MT5 and forex trading.

Signed-off-by: TIANHE <TIANHE@GMAIL.COM>
2026-01-13 04:01:42 +08:00
parent 7527d73f25
commit e095f9be7e
21 changed files with 2717 additions and 51 deletions
@@ -0,0 +1,215 @@
+# MetaTrader 5 (MT5) Trading Guide
+
+QuantDinger supports forex live trading via MetaTrader 5 terminal.
+
+## Overview
+
+This feature enables automated forex trading execution through your MetaTrader 5 account. Once configured, your trading strategies can automatically place orders via the MT5 API.
+
+## Prerequisites
+
+- MetaTrader 5 account with a forex broker
+- MT5 terminal installed (Windows only)
+- Market data subscription (for real-time quotes)
+
+## Installation
+
+The `MetaTrader5` library is already included in `requirements.txt`. If you need to install manually:
+
+```bash
+pip install MetaTrader5
+```
+
+> **Note**: The MetaTrader5 Python library only works on Windows. For Linux/Mac deployments, consider using a Windows VM or a remote Windows server.
+
+## MT5 Terminal Configuration
+
+1. Download and install MetaTrader 5 from your broker or [official website](https://www.metatrader5.com/)
+2. Login to your trading account
+3. Go to **Tools** → **Options** → **Expert Advisors**
+4. Enable:
+   - ✅ Allow algorithmic trading
+   - ✅ Allow DLL imports (optional, may be needed for some features)
+5. Click OK
+
+## Strategy Configuration
+
+When creating a forex strategy, configure the MT5 connection in the "Live Trading" section:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **Forex Broker** | Select "MetaTrader 5" | - |
+| **Server** | Broker server name | `ICMarkets-Demo` |
+| **Account Number** | MT5 login number | `12345678` |
+| **Password** | MT5 password | `****` |
+| **MT5 Terminal Path** | Terminal path (optional) | `C:\Program Files\MetaTrader 5\terminal64.exe` |
+
+> **Note**: If MT5 terminal is installed in the default location, you can leave the "MT5 Terminal Path" field empty. Only fill in the full path if MT5 is installed in a custom location.
+
+## Symbol Format
+
+| Market | Format | Examples |
+|--------|--------|----------|
+| Forex | Currency pair | `EURUSD`, `GBPUSD`, `USDJPY` |
+| Metals | XAU/XAG pairs | `XAUUSD`, `XAGUSD` |
+| Indices | CFD symbols | `US30`, `US500`, `DE40` |
+
+> **Note**: Symbol names may vary by broker. Some brokers use suffixes like `EURUSDm`, `EURUSD.raw`, etc. Check your broker's symbol list.
+
+## Lot Size Reference
+
+| Type | Units | Example |
+|------|-------|---------|
+| Standard Lot | 100,000 | 1.0 lot = 100,000 EUR |
+| Mini Lot | 10,000 | 0.1 lot = 10,000 EUR |
+| Micro Lot | 1,000 | 0.01 lot = 1,000 EUR |
+
+## Trading Flow
+
+```
+Strategy Signal → Pending Order Queue → MT5 Execution → Position Update
+```
+
+1. Your strategy generates a buy/sell signal
+2. The signal is queued as a pending order
+3. The background worker connects to MT5 and executes the order
+4. Position and trade records are updated
+
+## Supported Signal Types
+
+| Signal | Action | Description |
+|--------|--------|-------------|
+| `open_long` | BUY | Open a long position |
+| `add_long` | BUY | Add to existing long position |
+| `close_long` | SELL | Close long position |
+| `reduce_long` | SELL | Reduce long position |
+| `open_short` | SELL | Open a short position |
+| `add_short` | SELL | Add to existing short position |
+| `close_short` | BUY | Close short position |
+| `reduce_short` | BUY | Reduce short position |
+
+## API Endpoints
+
+### Connection Management
+
+```
+GET  /api/mt5/status          # Get connection status
+POST /api/mt5/connect         # Connect to MT5 terminal
+POST /api/mt5/disconnect      # Disconnect
+```
+
+### Account Queries
+
+```
+GET  /api/mt5/account         # Account information
+GET  /api/mt5/positions       # Open positions
+GET  /api/mt5/orders          # Pending orders
+GET  /api/mt5/symbols         # Available symbols
+```
+
+### Trading
+
+```
+POST   /api/mt5/order         # Place order
+POST   /api/mt5/close         # Close position
+DELETE /api/mt5/order/<id>    # Cancel pending order
+```
+
+### Market Data
+
+```
+GET  /api/mt5/quote?symbol=EURUSD
+```
+
+## Usage Examples
+
+### Test Connection (via curl)
+
+```bash
+# Using default terminal path
+curl -X POST http://localhost:5000/api/mt5/connect \
+  -H "Content-Type: application/json" \
+  -d '{"login": 12345678, "password": "your_password", "server": "ICMarkets-Demo"}'
+
+# With custom terminal path
+curl -X POST http://localhost:5000/api/mt5/connect \
+  -H "Content-Type: application/json" \
+  -d '{"login": 12345678, "password": "your_password", "server": "ICMarkets-Demo", "terminal_path": "C:\\Program Files\\MetaTrader 5\\terminal64.exe"}'
+```
+
+### Place Market Order
+
+```bash
+# Buy 0.1 lot EURUSD
+curl -X POST http://localhost:5000/api/mt5/order \
+  -H "Content-Type: application/json" \
+  -d '{"symbol": "EURUSD", "side": "buy", "volume": 0.1}'
+
+# Sell 0.5 lot XAUUSD
+curl -X POST http://localhost:5000/api/mt5/order \
+  -H "Content-Type: application/json" \
+  -d '{"symbol": "XAUUSD", "side": "sell", "volume": 0.5}'
+```
+
+### Place Limit Order
+
+```bash
+curl -X POST http://localhost:5000/api/mt5/order \
+  -H "Content-Type: application/json" \
+  -d '{"symbol": "EURUSD", "side": "buy", "volume": 0.1, "orderType": "limit", "price": 1.0800}'
+```
+
+### Close Position
+
+```bash
+curl -X POST http://localhost:5000/api/mt5/close \
+  -H "Content-Type: application/json" \
+  -d '{"ticket": 123456789}'
+```
+
+## Important Notes
+
+1. **MT5 terminal must be running**: The terminal must be open and logged in before trading
+2. **Windows only**: The MetaTrader5 Python library only works on Windows
+3. **Broker symbol names**: Symbol names vary by broker, check your broker's symbol list
+4. **Demo account first**: Test with a demo account before using real funds
+5. **Market hours**: Forex trades 24/5, check specific market hours for other instruments
+6. **Leverage**: Forex trading uses leverage. Be aware of margin requirements
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| ImportError | MetaTrader5 not installed | `pip install MetaTrader5` |
+| ImportError | Not on Windows | Use a Windows machine or VM |
+| Connection failed | Terminal not running | Start MT5 and login |
+| Connection failed | Wrong credentials | Verify login/password/server |
+| Symbol not found | Invalid symbol | Check broker's symbol list |
+| Trade not allowed | Trading disabled | Enable algo trading in MT5 options |
+| Order rejected | Insufficient margin | Check account balance and margin |
+
+## Docker Deployment
+
+When running QuantDinger in Docker, MT5 trading requires:
+
+1. **Windows host**: Docker Desktop on Windows, or Windows Server
+2. **MT5 on host**: Run MT5 terminal on the Windows host
+3. **Network access**: Container must be able to access the host's MT5 terminal
+
+For Linux/Mac deployments, consider:
+- Running QuantDinger backend on a Windows VM
+- Using a remote Windows server for MT5 connection
+
+## Security Recommendations
+
+- Use a dedicated trading account
+- Test with demo account first
+- Set appropriate lot sizes and risk limits
+- Monitor positions regularly
+- Keep MT5 terminal updated
+- Use strong passwords
+
+## See Also
+
+- [Python Strategy Development Guide](STRATEGY_DEV_GUIDE.md)
+- [MetaTrader 5 Python Documentation](https://www.mql5.com/en/docs/python_metatrader5)