MT5 Trade Split Manager 🤖

🤖 AI-Agent Friendly | Professional-grade MetaTrader 5 Expert Advisor with intelligent order splitting, automatic trailing stop loss, and REST API integration for any MT5 symbol (Gold/XAUUSD and Silver/XAGUSD included as examples). Ships with a Model Context Protocol (MCP) server for native Claude integration and other AI agents.

🤖 Why AI-Agent Friendly?

This system is designed for seamless integration with AI agents like Claude AI, ChatGPT, and other LLMs:

• 🔌 REST API First - Simple JSON endpoints that AI agents can easily call
• 📝 Natural Language Processing - AI agents can parse trading signals and convert to API calls
• 🔄 Stateless Design - Each API call is independent, perfect for AI workflows
• 📊 Structured Responses - JSON responses that AI can parse and act upon
• 🛡️ Safe Defaults - Smart order type detection prevents common AI mistakes
• 📚 Well-Documented - Complete API docs for AI agent training/prompts

Example AI Agent Workflow:

User: "Buy Gold at 4100 with 30-pip TPs"
AI Agent: Parses signal → Calls REST API → Monitors response
System: Splits order → Manages positions → Returns status

🚀 Key Features

• ✅ Automatic Order Splitting - Splits a single order into 1-10 positions with configurable volume distribution (defaults to 60/10/10/10/10 for 5 levels)
• ✅ Smart Trailing Stop Loss - Automatically moves SL to breakeven when TP2 is reached
• ✅ Dual TP Structures - Supports both 15-pip and 30-pip initial TP configurations
• ✅ Safe Shutdown Mode - Protects positions when EA is offline
• ✅ REST API Integration - FastAPI server for external signal processing
• ✅ MCP Server - Native Model Context Protocol server so Claude Code / Claude Desktop can inspect and control MT5 directly
• ✅ TCP Socket Communication - High-performance bidirectional communication
• ✅ Order Type Safety - Validates STOP/LIMIT (and SL/TP sides) against the live market and rejects wrong-side orders instead of silently reinterpreting your intent
• ✅ Position Recovery - Persists group state to disk and rebuilds tracking on restart, reconciling against live orders (survives broker comment rewrites)
• ✅ Any-Symbol Support - Works on any MT5 symbol; volumes snap to the broker's lot step and prices normalize to the symbol's digits (Gold/XAUUSD and Silver/XAGUSD are examples, not limits)
• ✅ Risk Management - Daily loss limits, max positions, spread checks
• ✅ AI Agent Ready - Perfect for Claude AI, ChatGPT, and automation workflows

📋 Table of Contents

• Quick Start
• Architecture
• Split Order System
• Trailing Stop Logic
• Safe Shutdown Mode
• API Documentation
• MCP Server
• Configuration
• Installation
• Usage Examples
• Troubleshooting
• FAQ
• License

🎯 Quick Start

Prerequisites

• MetaTrader 5 terminal
• Python 3.8 or higher
• Basic understanding of Forex/CFD trading

1. Install Python Dependencies

pip install -r requirements.txt

2. Start the Server

python server.py

The server will start on:

• REST API: http://localhost:8080
• TCP Server: 127.0.0.1:5555

3. Load EA in MT5

1. Open MetaEditor (F4 in MT5)
2. Compile bulk-add-signals.mq5 (F7)
3. Drag EA onto any chart
4. Enable "Allow DLL imports" in EA settings
5. Check Experts tab for connection confirmation

4. Place Your First Order

curl -X POST http://localhost:8080/order \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "XAUUSD",
    "order_type": "BUY_STOP",
    "price": 4100.0,
    "sl": 4096.0,
    "tp_levels": [4103.0, 4106.0, 4109.0, 4112.0, 4115.0],
    "lot_size": 0.1
  }'

🏗️ Architecture

┌─────────────┐      REST API       ┌──────────────┐      TCP Socket      ┌─────────────┐
│   External  │ ─────────────────> │    Python    │ ──────────────────> │   MT5 EA    │
│   Client    │   POST /order      │ FastAPI +    │   JSON Commands     │  (Client)   │
│  (Claude AI)│                     │  TCP Server  │                     │             │
└─────────────┘ <───────────────── └──────────────┘ <────────────────── └─────────────┘
                   JSON Response         :5555              Response           Execute
                   (ticket #)            Queue                                  Trade

Communication Flow

1. External client sends REST API request to FastAPI (port 8080)
2. Python server queues command and waits for MT5 connection
3. MT5 EA connects via TCP socket every 500ms (configurable)
4. Server sends queued command as JSON
5. EA parses, validates, and executes trade
6. EA sends response back through socket
7. Server returns response to original API caller

💡 Split Order System

Why Split Orders?

Traditional single-TP orders force you to choose between:

• Taking profit early (leaving money on the table)
• Holding for larger profit (risking reversal)

Solution: Split one order into 1 to 10 positions, each with its own TP!

Volume Distribution

You choose how many TP levels to send (1-10). If you don't send a volume_split, the EA/server apply a default weighting:

• 1 level → the whole lot goes to that single TP ([1.0]).
• N ≥ 2 levels → TP1 gets 60% and the remaining 40% is shared evenly across the other N-1 levels. For 5 levels this reproduces the original 60/10/10/10/10 distribution exactly, so existing 5-level clients are unchanged.

When you place 0.1 lot with the default 5-level split, the EA creates 5 separate orders:

| Order | Volume | % of Total | Take Profit | Purpose | |-------|--------|------------|-------------|---------| | TP1 | 0.06 | 60% | 15 pips | Secure majority profit quickly | | TP2 | 0.01 | 10% | 45 pips | Trailing SL trigger point | | TP3 | 0.01 | 10% | 75 pips | Medium-term profit | | TP4 | 0.01 | 10% | 105 pips | Extended profit | | TP5 | 0.01 | 10% | 135 pips | Maximum profit target |

Custom Volume Distribution

Send an optional volume_split array (one fraction per TP level) to override the default. The rules are validated on both the server (422 on failure) and the EA:

• Same length as tp_levels.
• Each entry ≥ 0, with at least one entry > 0.
• Sum ≈ 1.0 (accepted within [0.99, 1.01]).
• A 0 entry skips that level — no order is placed for it. This lets you keep a fixed 5-level TP ladder but only actually fill, say, TP1 and TP3.

Example — a 3-level 50/30/20 split:

"tp_levels": [4103.0, 4106.0, 4109.0],
"volume_split": [0.5, 0.3, 0.2]

Lot-Step Rounding

Each per-level volume is lot_size × ratio, floored down to the broker's lot step (SYMBOL_VOLUME_STEP). Any rounding leftover is added back to the level with the largest ratio so the totals still add up. If a non-zero level would floor to below the broker's minimum lot (SYMBOL_VOLUME_MIN), the whole order is rejected with a message naming the offending level and the smallest lot_size that would make it viable — the EA never silently drops a leg. Entry, SL, and every TP price are normalized to the symbol's digit precision before the order is sent.

TP Structure Options

Option 1: Standard Structure (15-pip initial)

• TP1: 15 pips
• TP2: 45 pips (+30)
• TP3: 75 pips (+30)
• TP4: 105 pips (+30)
• TP5: 135 pips (+30)

Option 2: Aggressive Structure (30-pip initial)

• TP1: 30 pips
• TP2: 60 pips (+30)
• TP3: 90 pips (+30)
• TP4: 120 pips (+30)
• TP5: 150 pips (+30)

Any Symbol, Correct Precision

Because you send absolute TP/SL/entry prices (not pip offsets), the system is not tied to any particular instrument. The EA reads the symbol's own volume step, minimum lot, and digit precision from MT5, so the same request format works on FX pairs, metals, indices, or crypto CFDs — whatever your broker exposes.

The pip figures used throughout these examples are just conveniences for the two symbols the project was first built around:

• Gold (XAUUSD): 1 pip ≈ 0.10 (e.g., 2650.00 → 2651.00)
• Silver (XAGUSD): 1 pip ≈ 0.01 (e.g., 29.50 → 29.51)

🎢 Trailing Stop Logic

Automatic Breakeven Protection

When TP2 closes (45 pips profit):

1. EA detects TP2 position is closed
2. Automatically moves SL to your actual TP1 price (the price you sent, not a fixed pip offset)
3. Remaining 30% of position (TP3, TP4, TP5) is now risk-free
4. Even if market reverses, you keep 15 pips profit on remaining positions

Example Scenario

Entry: Sell Stop @ 50.051 (Silver) Initial SL: 50.101 (5 pips above entry)

Trade Progression:

Price drops to 49.901 → TP1 closes (0.06 lots, 60% profit = +15 pips)
Price drops to 49.601 → TP2