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 Gold (XAUUSD) and Silver (XAGUSD) trading. Built for seamless integration with Claude AI 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 single order into 5 positions with optimized volume distribution (60%, 10%, 10%, 10%, 10%)
• ✅ 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
• ✅ 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 - Rebuilds tracking from existing orders on restart
• ✅ Multi-Symbol Support - Optimized for Gold (XAUUSD) and Silver (XAGUSD)
• ✅ 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
• 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 5 positions with different TPs!

Volume Distribution

When you place 0.1 lot, 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

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)

Pip Value Calibration

The EA automatically adjusts pip values based on symbol:

• 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 closes (0.01 lots, 10% profit = +45 pips)
                      → EA MOVES SL to 49.901 for TP3/TP4/TP5
                      → Position now RISK-FREE!

Price drops to 49.301 → TP3 closes (0.01 lots, protected, +75 pips)
Price drops to 49.001 → TP4 closes (0.01 lots, protected, +105 pips)
Price drops to 48.701 → TP5 closes (0.01 lots, protected, +135 pips)

If price reverses after TP2:

• Worst case: Remaining 30% closes at TP1 (49.901) = +15 pips
• You still profit on 60% at TP1 + 10% at TP2 + 30% at TP1
• Total locked profit: Better than breaking even!

🛡️ Safe Shutdown Mode

The Problem

When you close MT5 and the EA stops running:

• If TP2 gets hit while you're away, trailing SL won't activate
• TP3, TP4, TP5 remain at the original SL → risky!
• Market reversal could hit your SL instead of protecting profit

The Solution

Before closing MT5, activate safe shutdown mode:

curl -X POST http://localhost:8080/safe-shutdown

What It Does

1. Scans all order groups that haven't reached TP2 yet
2. Modifies TP2, TP3, TP4, TP5 → all moved to TP2 price level
3. Keeps TP1 unchanged (your quick profit)
4. Works on both pending orders and open positions

Before vs After

Before Safe Shutdown:

TP1: 15 pips (0.06 lots, 60%)
TP2: 45 pips (0.01 lots, 10%)
TP3: 75 pips (0.01 lots, 10%)
TP4: 105 pips (0.01 lots, 10%)
TP5: 135 pips (0.01 lots, 10%)

After Safe Shutdown:

TP1: 15 pips (0.06 lots, 60%) ← unchanged
TP2: 45 pips (0.01 lots, 10%)
TP3: 45 pips (0.01 lots, 10%) ← moved to TP2!
TP4: 45 pips (0.01 lots, 10%) ← moved to TP2!
TP5: 45 pips (0.01 lots, 10%) ← moved to TP2!

Benefits

✅ All remaining positions (40%) will close at maximum 45 pips
✅ No manual monitoring needed while away
✅ Safe to close MT5 and sleep/leave
✅ Guarantees minimum profit even if EA is offline

Response Format

{
  "success": true,
  "message": "Safe shutdown applied",
  "groups_modified": 3,
  "pending_orders_modified": 12,
  "open_positions_modified": 8,
  "details": [
    {"group": "XAUUSD_4065.000_1234567890", "modified": 4},
    {"group": "XAUUSD_4053.000_1234567891", "modified": 4},
    {"group": "XAUUSD_4012.000_1234567892", "modified": 4}
  ]
}

📚 API Documentation

Base URL

http://localhost:8080

Endpoints

1. Health Check

GET /health

Check if server is running.

Response:

{
  "status": "healthy",
  "tcp_host": "127.0.0.1",
  "tcp_port": 5555
}

2. Place Order

POST /order

Place a new order with automatic splitting.

Request Body:

{
  "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,
  "deviation": 3,
  "comment": "My Trade",
  "magic_number": 20250117
}

Parameters:

• symbol (string): Trading symbol ("XAUUSD" or "XAGUSD")
• order_type (string): "BUY_STOP", "SELL_STOP", "BUY_LIMIT", or "SELL_LIMIT". The price must be on the correct side of the market for the type (e.g. BUY_STOP above the ask); wrong-side requests are rejected with an explanatory message rather than converted.
• price (float): Entry price
• sl (float): Stop loss price
• tp_levels (array): 5 take profit levels
• lot_size (float): Total volume (will be split into 5 orders)
• deviation (int, optional): Maximum price deviation in pips
• comment (string, optional): Order comment
• magic_number (int, optional): Magic number for identification

Response:

{
  "success": true,
  "message": "Order placed successfully",
  "ticket": 171645717
}

3. Get Positions

GET /positions

Get all open positions.

Response:

{
  "success": true,
  "positions": [
    {
      "ticket": 123456,
      "symbol": "XAUUSD",
      "type": "BUY",
      "volume": 0.06,
      "price_open": 4100.0,
      "sl": 4096.0,
      "tp": 4103.0,
      "profit": 18.50
    }
  ]
}

4. Get Pending Orders

GET /orders

Get all pending orders.

Response:

{
  "success": true,
  "orders": [
    {
      "ticket": 171645717,
      "symbol": "XAUUSD",
      "type": "BUY_STOP",
      "volume": 0.06,
      "price": 4100.0,
      "sl": 4096.0,
      "tp": 4103.0
    }
  ]
}

5. Delete Order

DELETE /order/{ticket}

Cancel a pending order.

Response:

{
  "success": true,
  "message": "Order deleted",
  "ticket": 171645717
}

6. Close Position

DELETE /position/{ticket}

Close an open position.

Response:

{
  "success": true,
  "message": "Position closed",
  "ticket": 123456
}

7. Get Statistics

GET /stats

Get account statistics and EA status.

Response:

{
  "success": true,
  "stats": {
    "balance": 10000.00,
    "equity": 10050.00,
    "margin": 500.00,
    "free_margin": 9550.00,
    "profit": 50.00,
    "total_positions": 5,
    "total_orders": 15,
    "tracked_groups": 3,
    "magic_number": 20250117
  }
}

8. Safe Shutdown

POST /safe-shutdown

Activate safe shutdown mode - consolidate all TPs to TP2 level.

Response:

{
  "success": true,
  "message": "Safe shutdown applied",
  "groups_modified": 3,
  "pending_orders_modified": 12,
  "open_positions_modified": 8
}

⚙️ Configuration

config.json

{
  "mt5": {
    "zmq_port": 5555,
    "default_lot_size": 0.1
  },
  "symbols": {
    "gold": "XAUUSD",
    "silver": "XAGUSD"
  },
  "risk_management": {
    "max_daily_loss_percent": 5.0,
    "max_positions": 10
  }
}

EA Input Parameters

Configure in MT5 when attaching EA to chart:

Parameter	Default	Description
ServerHost	"127.0.0.1"	Python server IP address
ServerPort	5555	TCP server port
MagicNumber	20250117	Unique identifier for EA orders
SocketCheckIntervalMs	500	How often to check for commands (ms)
MaxSpreadPips	10	Maximum allowed spread in pips
MaxDailyLossPercent	5.0	Stop trading if daily loss exceeds %

🔒 Security

This API can place and close real trades, so it is locked down by default:

• Localhost only — the HTTP server binds to 127.0.0.1 unless you set HOST=0.0.0.0.
• Optional API key — set the API_KEY environment variable and every trading endpoint (everything except / and /health) requires a matching X-API-Key header:

API_KEY=your-secret HOST=0.0.0.0 python server.py

curl -X POST http://localhost:8080/order \
  -H "X-API-Key: your-secret" -H "Content-Type: application/json" \
  -d '{ ... }'

If you expose the server beyond localhost (e.g. Docker with HOST=0.0.0.0) always set API_KEY. The server prints a warning if you don't.

📦 Installation

Option 1: Manual Installation

1. Clone the repository:

git clone https://github.com/yourusername/mt5-bulk-order-manager.git
cd mt5-bulk-order-manager

1. Install Python dependencies:

pip install -r requirements.txt

1. Copy MQL5 files to MT5:

cp bulk-add-signals.mq5 "~/MetaTrader 5/MQL5/Experts/"

1. Start the server:

python server.py

Option 2: Docker Installation

docker-compose up -d

The server will be available at http://localhost:8080

💻 Usage Examples

Example 1: Gold Buy Stop 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
  }'

This creates 5 orders:

• 0.06 lots @ TP 4103.0 (30 pips)
• 0.01 lots @ TP 4106.0 (60 pips)
• 0.01 lots @ TP 4109.0 (90 pips)
• 0.01 lots @ TP 4112.0 (120 pips)
• 0.01 lots @ TP 4115.0 (150 pips)

Example 2: Silver Sell Stop Order

curl -X POST http://localhost:8080/order \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "XAGUSD",
    "order_type": "SELL_STOP",
    "price": 29.50,
    "sl": 29.65,
    "tp_levels": [29.35, 29.05, 28.75, 28.45, 28.15],
    "lot_size": 0.5
  }'

Example 3: Check All Positions

curl http://localhost:8080/positions

Example 4: Activate Safe Shutdown

curl -X POST http://localhost:8080/safe-shutdown

🔧 Troubleshooting

EA Not Connecting to Server

Symptoms: EA shows "Not connected" in Experts tab

Solutions:

1. Check Python server is running: curl http://localhost:8080/health
2. Verify port 5555 is listening: netstat -an | grep 5555
3. Check firewall allows local connections
4. Ensure "Allow DLL imports" is enabled in EA settings
5. Check EA logs in MT5 Experts tab for error messages

Orders Failing with "Invalid Price"

Symptoms: All split orders fail immediately

Cause: The order type doesn't match the price's position relative to the market.

Solution: The EA validates this and returns a clear message instead of silently changing your order. Pick the type that matches your intent:

• Entry above market → BUY_STOP (breakout) or SELL_LIMIT (fade)
• Entry below market → SELL_STOP (breakout) or BUY_LIMIT (dip-buy)

SL and TP prices must also be on the correct side of the entry, or the order is rejected. Recompile the EA with the latest code.

Port Already in Use

Symptoms: Server fails to start with "Address already in use"

Solution:

# Find and kill process using port 8080
lsof -ti:8080 | xargs kill -9

# Find and kill process using port 5555
lsof -ti:5555 | xargs kill -9

# Restart server
python server.py

Trailing Stop Not Activating

Symptoms: TP2 closes but SL doesn't move to TP1

Possible Causes:

1. EA was restarted after orders placed (group tracking lost)
2. Orders placed manually instead of through API
3. Comment format doesn't match expected pattern

Solution:

• Always place orders through the API
• Don't restart EA while positions are open
• Check order comments include GROUP and TP fields

Safe Shutdown Not Working

Symptoms: Command succeeds but TPs not modified

Cause: EA not compiled with latest code

Solution:

1. Open MetaEditor (F4)
2. Open bulk-add-signals.mq5
3. Press F7 to recompile
4. Restart EA on chart
5. Try safe shutdown command again

❓ FAQ

Q: Can I use this with other symbols besides Gold and Silver?
A: The code is optimized for XAUUSD and XAGUSD pip values. For other symbols, you'll need to adjust the pipValue calculation in the MQL5 code.

Q: What happens if I restart MT5 while positions are open?
A: The EA has position recovery logic that rebuilds order group tracking from position comments. However, trailing SL won't trigger during the restart period.

Q: Can I change the volume distribution (60/10/10/10/10)?
A: Yes, edit the volumes[] array in the ExecuteOrder() function in bulk-add-signals.mq5.

Q: Does this work on MT4?
A: No, this is specifically designed for MT5. MT4 uses a different API and doesn't support the same socket operations.

Q: Can I run multiple EAs with different magic numbers?
A: Yes, each EA instance can have a unique magic number. Configure it in the EA input parameters.

Q: Is there a web interface?
A: Currently, the system uses a REST API. You can build a web frontend that calls the API endpoints.

Q: How do I backtest this EA?
A: The EA uses socket communication which isn't available in Strategy Tester. For backtesting, you'd need to modify the code to use simulated data instead of TCP sockets.

Q: What's the minimum lot size?
A: Depends on your broker. Since orders are split into 0.01 lot increments, your broker must support 0.01 lots (micro lots).

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

⚠️ Disclaimer

This software is for educational purposes only. Trading forex and CFDs involves substantial risk of loss. Past performance is not indicative of future results. Always test on a demo account first.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

🎯 Roadmap

• Web-based dashboard for monitoring positions
• Telegram bot integration for alerts
• Support for additional symbols
• Advanced risk management presets
• Trade journal and analytics
• Multi-account support

🙏 Acknowledgments

• Built with FastAPI
• MetaTrader 5 by MetaQuotes
• Inspired by professional trading strategies

---

Made with ❤️ for algorithmic traders

Keywords: MetaTrader 5, MT5, Expert Advisor, EA, Gold Trading, XAUUSD, Silver Trading, XAGUSD, Forex Bot, Trading Bot, Algorithmic Trading, Automated Trading, Split Orders, Trailing Stop, Risk Management, FastAPI, Python Trading, MQL5, Trading API, REST API, Socket Trading