rckrdmrd/trading-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8f0235c096
trading-platform/docs/01-arquitectura/ARQUITECTURA-EA-BRIDGE-MT4.md
Adrian Flores Cortes 1f47507833 docs: Move EA bridge architecture to organized location 
Moved docs/architecture/EA-BRIDGE-ARCHITECTURE.md to
docs/01-arquitectura/ARQUITECTURA-EA-BRIDGE-MT4.md

Part of ST3.2 Documentation Reorganization.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 18:58:31 -06:00

343 lines
14 KiB
Markdown
Raw Blame History

# EA Bridge Architecture
## Overview
The EA Bridge is a distributed architecture that enables AI-driven trading decisions to be executed on MetaTrader 4 (MT4) terminals. It provides a standardized interface between the Trading Platform's AI components and broker execution.
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────────────┐
│ AI Layer (Decision Making) │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ LLM Agent │ │ Trading │ │ ML Engine │ │
│ │ (:8003) │ │ Agents(:8004)│ │ (:8001) │ │
│ └──────┬──────┘ └──────┬───────┘ └────────────────────────┘ │
│ │ │ │
└─────────┼────────────────┼───────────────────────────────────────┘
│ MCP Protocol │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ MCP Layer (Protocol Bridge) │
│ ┌─────────────────────────┐ ┌─────────────────────────────┐ │
│ │ MCP MT4 Connector │ │ MCP Binance Connector │ │
│ │ (:3605) │ │ (:3606) │ │
│ │ - 6 Trading Tools │ │ - 7 Trading Tools │ │
│ │ - Zod Validation │ │ - Rate Limiting │ │
│ └───────────┬─────────────┘ └─────────────────────────────┘ │
│ │ │
└──────────────┼───────────────────────────────────────────────────┘
│ HTTP REST
▼
┌─────────────────────────────────────────────────────────────────┐
│ Gateway Layer (Risk & Routing) │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ MT4 Gateway Service (:8005) ││
│ │ - Multi-agent orchestration ││
│ │ - Risk Management validation ││
│ │ - Agent Registry (Atlas, Orion, Nova) ││
│ └───────────┬─────────────┬────────────────┬──────────────────┘│
└──────────────┼─────────────┼────────────────┼────────────────────┘
│ │ │ HTTP REST
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Execution Layer (MT4 Terminals) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Terminal 1 │ │ Terminal 2 │ │ Terminal 3 │ │
│ │ Atlas :8081 │ │ Orion :8082 │ │ Nova :8083 │ │
│ │ Conservative│ │ Moderate │ │ Aggressive │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
└─────────┼────────────────┼────────────────┼──────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────┐
│ Broker Server (EBC) │
│ Real order execution & fills │
└─────────────────────────────────────────┘
```
## Components
### 1. MCP MT4 Connector
**Location:** `apps/mcp-mt4-connector/`
**Technology:** TypeScript/Node.js (Express.js)
**Port:** 3605
Exposes 6 MCP-compatible tools:
| Tool | Risk Level | Description |
|------|------------|-------------|
| `mt4_get_account` | LOW | Get balance, equity, margin, leverage |
| `mt4_get_positions` | LOW | List open positions with P/L |
| `mt4_get_quote` | LOW | Get bid/ask/spread for symbol |
| `mt4_execute_trade` | HIGH | Execute BUY/SELL with SL/TP |
| `mt4_close_position` | HIGH | Close position (full or partial) |
| `mt4_modify_position` | MEDIUM | Modify SL/TP levels |
**Key Files:**
- `src/index.ts` - Express server with MCP protocol endpoints
- `src/services/mt4-client.ts` - HTTP client wrapper for MT4 Gateway
- `src/tools/` - Individual tool implementations
### 2. MT4 Gateway
**Location:** `apps/mt4-gateway/`
**Technology:** Python/FastAPI
**Port:** 8005
Provides:
- Multi-agent orchestration
- Risk validation before execution
- Agent configuration management
- Connection pooling to terminals
**Key Files:**
- `src/main.py` - FastAPI application
- `src/api/routes.py` - REST API endpoints
- `src/providers/mt4_bridge_client.py` - Async HTTP client
- `config/agents.yml` - Agent definitions
### 3. EA Bridge (Expert Advisor)
**Location:** External (MT4 Terminal)
**Technology:** MQL4
**Ports:** 8081, 8082, 8083
The Expert Advisor runs within MetaTrader 4 and exposes a REST API:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/status` | GET | Connection health check |
| `/account` | GET | Account info (balance, equity) |
| `/tick/{symbol}` | GET | Current bid/ask/spread |
| `/positions` | GET | Open positions list |
| `/trade` | POST | Execute trade order |
| `/history` | GET | Trade history |
| `/symbols` | GET | Available symbols |
## Trading Agents
Three pre-configured agents with different risk profiles:
| Agent | Strategy | Risk Profile | Port |
|-------|----------|--------------|------|
| Atlas | AMD Phase Detection | 1% per trade, max 1 position | 8081 |
| Orion | ICT Concepts | 1.5% per trade, max 2 positions | 8082 |
| Nova | Mixed (AMD + ICT) | 2% per trade, max 3 positions | 8083 |
## Data Flow
### Trade Execution Flow
```
1. User Request
"Buy 0.1 lots XAUUSD with SL at 2640"
│
▼
2. LLM Agent (Intent Recognition)
Identifies: symbol=XAUUSD, action=buy, lots=0.1, stopLoss=2640
│
▼
3. MCPOrchestrator (Venue Routing)
Determines: XAUUSD → MT4 (forex/metals)
│
▼
4. MCP MT4 Connector (Protocol)
Validates input with Zod schemas
Calls mt4_execute_trade tool
│
▼
5. MT4 Gateway (Risk Check)
Validates: lot size, margin, max positions
Routes to correct agent terminal
│
▼
6. EA Bridge (Execution)
POST /trade → MT4 Terminal
│
▼
7. Broker Server
Order executed, ticket assigned
│
▼
8. Response Flow (Reverse Path)
Ticket #12345, entry 2650.50, SL 2640.00
```
### Portfolio Query Flow
```
1. MCPOrchestrator.get_combined_portfolio()
│
├─────────────────────────────────┐
▼ ▼
2a. MCP MT4 Connector 2b. MCP Binance Connector
GET /account GET /account
│ │
▼ ▼
3a. MT4 Gateway 3b. Binance API
GET /account GET /account
│ │
▼ ▼
4a. EA Bridge 4b. Binance Exchange
Returns account info Returns account info
│ │
└───────────┬─────────────────────┘
▼
5. MCPOrchestrator (Aggregation)
Combined portfolio:
- Total Balance: $X (MT4) + $Y (Binance)
- Total Equity: $X' + $Y'
- All Positions: [MT4 positions] + [Binance positions]
```
## Configuration
### Environment Variables
**MCP MT4 Connector:**
```env
PORT=3605
MT4_GATEWAY_HOST=localhost
MT4_GATEWAY_PORT=8005
MT4_GATEWAY_AUTH_TOKEN=your-secure-token
REQUEST_TIMEOUT=10000
LOG_LEVEL=info
```
**MT4 Gateway:**
```env
MT4_BRIDGE_HOST=localhost
MT4_BRIDGE_PORT=8081
MT4_BRIDGE_AUTH_TOKEN=secret_agent_1
API_PORT=8005
```
### Agent Configuration (agents.yml)
```yaml
agents:
- id: agent_1
name: Atlas
description: Conservative AMD strategy
port: 8081
enabled: true
max_positions: 1
risk_per_trade: 0.01
- id: agent_2
name: Orion
description: Moderate ICT strategy
port: 8082
enabled: false
max_positions: 2
risk_per_trade: 0.015
- id: agent_3
name: Nova
description: Aggressive mixed strategy
port: 8083
enabled: false
max_positions: 3
risk_per_trade: 0.02
```
## Risk Management
### Per-Trade Limits
- Max risk: 1-2% of equity
- Max position size: 10% of equity
- Lot size range: 0.01 - 10.0
### Per-Account Limits
- Max daily drawdown: 5%
- Max total drawdown: 20%
- Max open positions: Agent-dependent (1-3)
### Validation Flow
```
Request → Lot Size Check → Margin Check → Position Limit Check → Execute
```
## Security
1. **Authentication:** Bearer token in HTTP headers
2. **Validation:** Zod schemas (TypeScript), Pydantic models (Python)
3. **Error Handling:** Graceful degradation on failures
4. **Health Checks:** Connection verification before operations
## Integration Points
| Service | Port | Purpose |
|---------|------|---------|
| LLM Agent | 8003 | AI decision making |
| Trading Agents | 8004 | Strategy execution |
| ML Engine | 8001 | Signal generation |
| Backend API | 3000 | User interface |
| PostgreSQL | 5432 | Data persistence |
## Deployment
```
┌────────────────────────────────────────────────────────────┐
│ Linux/Docker Environment │
│ - MT4 Gateway (:8005) │
│ - MCP Connectors (:3605, :3606) │
│ - AI Services (:8001, :8003, :8004) │
└────────────────────────────────────────────────────────────┘
│
HTTP/REST (Network)
│
▼
┌────────────────────────────────────────────────────────────┐
│ Windows Environment │
│ - MT4 Terminal + EA Bridge (:8081) │
│ - MT4 Terminal + EA Bridge (:8082) │
│ - MT4 Terminal + EA Bridge (:8083) │
└────────────────────────────────────────────────────────────┘
```
## Troubleshooting
### Common Issues
1. **Connection Refused (port 8081-8083)**
- Verify MT4 terminal is running
- Check EA is attached to chart
- Verify firewall rules
2. **Authentication Failed**
- Check AUTH_TOKEN matches in .env files
- Verify token format (Bearer prefix)
3. **Trade Rejected**
- Check margin availability
- Verify symbol is available
- Check market is open
4. **Timeout Errors**
- Increase REQUEST_TIMEOUT
- Check network latency
- Verify EA is responding
### Health Check Commands
```bash
# Check MCP Connector
curl http://localhost:3605/health
# Check MT4 Gateway
curl http://localhost:8005/health
# Check EA Bridge directly
curl http://localhost:8081/status
```
## Related Documentation
- [MCPOrchestrator Integration](./MCP-ORCHESTRATOR.md)
- [Trading Agents Configuration](./TRADING-AGENTS.md)
- [Risk Management Policies](./RISK-MANAGEMENT.md)
Reference in New Issue View Git Blame Copy Permalink