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

## Deployment & Connection (Windows / Docker Options)

### Key takeaway (one sentence)

**The official MT5 Python library `MetaTrader5` depends on the MT5 Terminal running on Windows.**  
So the **backend process must run in a Windows environment that can access the MT5 Terminal** for this to work.

### Deployment options (pick the right path first)

| Deployment | MT5 usable? | Recommendation | Notes |
|---|---:|---:|---|
| **Run backend natively on Windows (no backend container)** | ✅ | ⭐⭐⭐⭐⭐ | Most stable: backend and MT5 Terminal on the same machine. |
| **Run backend natively on Windows + Docker only for Postgres/Redis** | ✅ | ⭐⭐⭐⭐⭐ | Common in practice: infra containerized, trading connection stays on Windows host. |
| **Windows Docker Desktop (Linux containers) runs backend** | ❌ (not recommended) | ⭐ | Containers generally cannot use the host Windows MT5 Terminal directly. |
| **Linux server/cloud runs backend** | ❌ (not recommended) | ⭐ | `MetaTrader5` is typically Windows-only; use a Windows machine/gateway approach instead. |

### Recommended setup: Windows native backend + MT5 Terminal (optional Docker for DB/Redis)

**Prerequisites:**

- A **Windows** machine (local PC or Windows Server)
- MT5 Terminal installed and able to login (keep it open and logged in before trading)
- Python 3.10+ (PowerShell `py` launcher recommended)

**Install Windows-only dependencies:**

This repo provides `backend_api_python/requirements-windows.txt` (includes `MetaTrader5>=5.0.45`).

PowerShell:

```powershell
cd C:\path\to\QuantDinger\backend_api_python

py -m venv .venv
.\.venv\Scripts\Activate.ps1

py -m pip install -U pip
pip install -r requirements.txt
pip install -r requirements-windows.txt
```

**Configure backend `.env`:**

- `SECRET_KEY=...` (required)
- `ALLOW_LOCAL_DESKTOP_BROKERS=true` (defaults to true; if false, the server will reject IBKR/MT5 related calls)

Start the backend (entrypoint: `backend_api_python/run.py`):

```powershell
cd C:\path\to\QuantDinger\backend_api_python
.\.venv\Scripts\Activate.ps1
python run.py
```

Suggested quick checks after startup:

- Health check: `http://localhost:5000/api/health`
- MT5 status: `http://localhost:5000/api/mt5/status`

### Why MT5 often fails in Docker deployments

With Docker Desktop one-click deployments, the backend usually runs inside a **Linux container**:

- The official `MetaTrader5` library depends on the Windows MT5 Terminal (a local GUI app)
- Linux containers cannot directly call into the host MT5 Terminal
- Even if you install the package in the container, establishing a working connection is unlikely

**Suggestions:**

- If you do **not** need MT5: set `ALLOW_LOCAL_DESKTOP_BROKERS=false` in `backend_api_python/.env` so the UI can show a clear message instead of errors
- If you **must** use MT5: run the backend natively on Windows (recommended above), or implement a “Windows MT5 gateway/bridge” (container calls the gateway)

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

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