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:

hljs language-sql

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
✅ Smart Order Type Detection - Automatically converts STOP/LIMIT based on market price
✅ 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

🎯 Quick Start

Prerequisites

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

1. Install Python Dependencies

hljs language-bash

pip install -r requirements.txt

2. Start the Server

hljs language-bash

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

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

4. Place Your First Order

hljs language-bash

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

hljs language-scss

┌─────────────┐      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

External client sends REST API request to FastAPI (port 8080)
Python server queues command and waits for MT5 connection
MT5 EA connects via TCP socket every 500ms (configurable)
Server sends queued command as JSON
EA parses, validates, and executes trade
EA sends response back through socket
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):

EA detects TP2 position is closed
Automatically moves SL to TP1 price (15 pips from entry)
Remaining 30% of position (TP3, TP4, TP5) is now risk-free
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:

hljs language-vbnet

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:

hljs language-bash

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

What It Does

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

Before vs After

Before Safe Shutdown:

hljs language-makefile

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:

hljs language-vbnet

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

hljs language-json

{
  "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

hljs language-arduino

http://localhost:8080

Endpoints

1. Health Check

GET /health

Check if server is running.

Response:

hljs language-json

{
  "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:

hljs language-json

{
  "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" or "SELL_STOP"
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:

hljs language-json

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

3. Get Positions

GET /positions

Get all open positions.

Response:

hljs language-json

{
  "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:

hljs language-json

{
  "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:

hljs language-json

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

6. Close Position

DELETE /position/{ticket}

Close an open position.

Response:

hljs language-json

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

7. Get Statistics

GET /stats

Get account statistics and EA status.

Response:

hljs language-json

{
  "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:

hljs language-json

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

⚙️ Configuration

config.json

hljs language-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 %

📦 Installation

Option 1: Manual Installation

Clone the repository:

hljs language-bash

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

Install Python dependencies:

hljs language-bash

pip install -r requirements.txt

Copy MQL5 files to MT5:

hljs language-bash

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

Start the server:

hljs language-bash

python server.py

Option 2: Docker Installation

hljs language-bash

docker-compose up -d

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

💻 Usage Examples

Example 1: Gold Buy Stop Order

hljs language-bash

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

hljs language-bash

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

hljs language-bash

curl http://localhost:8080/positions

Example 4: Activate Safe Shutdown

hljs language-bash

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

🔧 Troubleshooting

EA Not Connecting to Server

Symptoms: EA shows "Not connected" in Experts tab

Solutions:

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

Orders Failing with "Invalid Price"

Symptoms: All split orders fail immediately

Cause: Order type doesn't match price position relative to market

Solution: The EA now auto-detects and converts:

SELL STOP above market → SELL LIMIT
BUY STOP below market → BUY LIMIT

Recompile the EA with the latest code.

Port Already in Use

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

Solution:

hljs language-bash

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

EA was restarted after orders placed (group tracking lost)
Orders placed manually instead of through API
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:

Open MetaEditor (F4)
Open bulk-add-signals.mq5
Press F7 to recompile
Restart EA on chart
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

mt5-trade-split-manager

MT5 Trade Split Manager 🤖

🤖 Why AI-Agent Friendly?

🚀 Key Features

📋 Table of Contents

🎯 Quick Start

Prerequisites

1. Install Python Dependencies

2. Start the Server

3. Load EA in MT5

4. Place Your First Order

🏗️ Architecture

Communication Flow

💡 Split Order System

Why Split Orders?

Volume Distribution

TP Structure Options

Pip Value Calibration

🎢 Trailing Stop Logic

Automatic Breakeven Protection

Example Scenario

🛡️ Safe Shutdown Mode

The Problem

The Solution

What It Does

Before vs After

Benefits

Response Format

📚 API Documentation

Base URL

Endpoints

1. Health Check

2. Place Order

3. Get Positions

4. Get Pending Orders

5. Delete Order

6. Close Position

7. Get Statistics

8. Safe Shutdown

⚙️ Configuration

config.json

EA Input Parameters

📦 Installation

Option 1: Manual Installation

Option 2: Docker Installation

💻 Usage Examples

Example 1: Gold Buy Stop Order

Example 2: Silver Sell Stop Order

Example 3: Check All Positions

Example 4: Activate Safe Shutdown

🔧 Troubleshooting

EA Not Connecting to Server

Orders Failing with "Invalid Price"

Port Already in Use

Trailing Stop Not Activating

Safe Shutdown Not Working

❓ FAQ

📄 License

🤝 Contributing

⚠️ Disclaimer

📞 Support

🎯 Roadmap

🙏 Acknowledgments

Similar Packages

Tags

Original Author

Publisher