ForexBot2/mt5.md

MT5 Auto-Execution Integration Plan

Context

ForexBot2 generates trade signals with full setups (entry, SL, TP) but currently only displays them in Telegram. The user wants fully automatic order execution via MetaTrader 5.

Constraint: MT5 runs on a separate Windows machine. The Python MetaTrader5 package requires Windows (COM interface). The bot runs on Linux. A network bridge is needed.

Broker: TIO Markets (demo first, live later via config change). Execution mode: Fully automatic for actionable signals (A+/A/B grades).

Architecture: REST API Bridge

Linux (telegram_bot.py)                    Windows (mt5_bridge.py)
========================                   ========================
Signal fires with TradeSetup               FastAPI server running
  -> mt5_client.execute_trade()              -> Wraps MetaTrader5 package
     POST /api/order  ─────── HTTP ───────>  -> mt5.order_send()
     <- {ticket: 12345}  <──── HTTP ──────   <- Returns ticket or error
  -> Telegram: "ORDER PLACED"              -> Idempotency via order_id

Why REST over WebSocket/file-sync: Stateless, debuggable, retry-safe. For a bot placing 1-5 trades/day, HTTP latency (5-50ms LAN) is negligible.

Files to Create/Modify

New Files

1. mt5_bridge/mt5_bridge.py — Windows-side FastAPI server (~200 lines)

• Wraps MetaTrader5 Python package
• Endpoints: /api/health, /api/account, /api/positions, /api/order (POST), /api/order/close (POST)
• Lot size calculation on bridge side (has access to mt5.symbol_info() for tick value, contract size, volume step)
• Idempotency: stores {order_id: ticket} to prevent duplicate orders on retry
• API key auth via X-API-Key header
• MT5 credentials from env vars: MT5_LOGIN, MT5_PASSWORD, MT5_SERVER, MT5_PATH

2. mt5_bridge/requirements.txt — Windows dependencies

• fastapi, uvicorn, MetaTrader5, pydantic

3. mt5_client.py — Linux-side async HTTP client (~150 lines)

• MT5ExecutionClient class with aiohttp
• execute_trade(setup: TradeSetup, quality: str) — sends order to bridge
• Symbol mapping: EURUSD=X -> EURUSD (TIO Markets format, configurable)
• Duplicate prevention: tracks open positions per symbol
• Retry: 3 attempts, exponential backoff, same order_id for idempotency
• Position sync: periodically calls /api/positions to stay in sync with MT5
• Graceful degradation: if bridge offline, logs warning, bot continues signal-only

Modified Files

4. config.py — Add MT5Config dataclass

@dataclass
class MT5Config:
    enabled: bool = False
    bridge_url: str = "http://192.168.1.100:8080"
    bridge_api_key: str = ""
    risk_pct: float = 1.0              # % of balance risked per trade
    max_open_positions: int = 3
    max_daily_trades: int = 10         # Circuit breaker
    magic_number: int = 234000         # Identifies ForexBot2 orders
    slippage_points: int = 20          # 2 pips for 5-digit brokers
    auto_execute_grades: List[str]     # ["A+", "A", "B"]
    symbol_map: Dict[str, str]         # Internal -> broker symbol

All overridable via env vars (MT5_BRIDGE_URL, MT5_RISK_PCT, etc.)

5. telegram_bot.py — Wire execution into signal flow

• In _scan_timeframe(): after sending Telegram messages, call mt5_client.execute_trade() for actionable signals
• In _handle_breach(): same pattern after breach scan produces actionable signal
• Add background task _mt5_position_sync_loop() for periodic position sync
• Add Telegram commands: /mt5status (bridge health + account info), /positions (open trades)
• Register new commands in set_my_commands()
• Execution result messages sent to Telegram (ticket # on success, error on failure)

6. requirements.txt — Add aiohttp>=3.9 (async HTTP for Linux-side client)

Safety Layers

1. Demo account first — MT5_SERVER=TIOMarkets-Demo
2. enabled: False default — must explicitly opt-in via MT5_ENABLED=true
3. Duplicate prevention — 3 layers: client-side tracking, bridge-side position check, idempotent order_id
4. Circuit breaker — max_daily_trades stops execution if too many orders fire
5. Position limit — max_open_positions caps concurrent exposure
6. Risk-based sizing — lot size from risk_pct of account balance, calculated on bridge with live tick values
7. Graceful degradation — bridge offline = signal-only mode, no crash

Position Sizing (calculated on Windows bridge)

risk_amount = balance * (risk_pct / 100)
tick_value = mt5.symbol_info(symbol).trade_tick_value
tick_size = mt5.symbol_info(symbol).trade_tick_size
sl_ticks = abs(entry - stop_loss) / tick_size
lot_size = risk_amount / (sl_ticks * tick_value)
lot_size = round_down(lot_size, volume_step)
lot_size = clamp(lot_size, volume_min, volume_max)

Bridge side is best because it has real-time tick_value (varies with exchange rates for cross pairs).

Symbol Mapping (TIO Markets)

Internal	MT5 Symbol
EURUSD=X	EURUSD
USDJPY=X	USDJPY
GBPUSD=X	GBPUSD
XAU/USD	XAUUSD

Configurable via MT5_SYMBOL_MAP env var (JSON) for broker variations.

Integration Points

In _scan_timeframe() (after line ~406):

mt5 = _get_mt5_client()
if mt5:
    for report in actionable:
        if report.trade_setup and report.signal_quality in mt5.config.auto_execute_grades:
            result = await mt5.execute_trade(report.trade_setup, report.signal_quality)
            # Send execution confirmation/error to Telegram

In _handle_breach() (after line ~477):

if report.trade_setup and report.signal_quality in mt5.config.auto_execute_grades:
    mt5 = _get_mt5_client()
    if mt5:
        result = await mt5.execute_trade(report.trade_setup, report.signal_quality)
        # Send execution confirmation/error to Telegram

New Telegram Commands

Command	Description
/mt5status	Bridge health, account balance/equity, open positions count
/positions	List all open MT5 positions with P/L

Implementation Order

1. config.py — Add MT5Config
2. mt5_bridge/mt5_bridge.py + requirements.txt — Windows bridge server
3. mt5_client.py — Linux HTTP client
4. telegram_bot.py — Wire execution + new commands
5. requirements.txt — Add aiohttp

Verification

1. Start bridge on Windows: python mt5_bridge.py -> verify curl /api/health returns MT5 connected
2. Test order via curl: POST /api/order with demo credentials -> verify order appears in MT5
3. Start bot on Linux with MT5_ENABLED=true -> verify /mt5status command works
4. Wait for actionable signal (or manually trigger scan) -> verify order placed + Telegram confirmation
5. Verify duplicate prevention: same signal shouldn't place second order
6. Kill bridge -> verify bot continues in signal-only mode without crashing

Windows Bridge Setup (one-time)

# On Windows machine:
pip install fastapi uvicorn MetaTrader5 pydantic

# Set environment variables:
set MT5_LOGIN=12345678
set MT5_PASSWORD=your-password
set MT5_SERVER=TIOMarkets-Demo
set MT5_PATH=C:\Program Files\MetaTrader 5\terminal64.exe
set BRIDGE_API_KEY=your-random-32-char-key
set BRIDGE_PORT=8080

# Run:
python mt5_bridge.py

Linux Bot Config (env vars)

MT5_ENABLED=true
MT5_BRIDGE_URL=http://<windows-ip>:8080
MT5_BRIDGE_API_KEY=your-random-32-char-key
MT5_RISK_PCT=1.0
MT5_MAX_OPEN_POSITIONS=3
MT5_AUTO_EXECUTE_GRADES=A+,A,B