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

14 KiB

Raw Permalink 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:

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:

MT4_BRIDGE_HOST=localhost
MT4_BRIDGE_PORT=8081
MT4_BRIDGE_AUTH_TOKEN=secret_agent_1
API_PORT=8005

Agent Configuration (agents.yml)

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

Authentication: Bearer token in HTTP headers
Validation: Zod schemas (TypeScript), Pydantic models (Python)
Error Handling: Graceful degradation on failures
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

Connection Refused (port 8081-8083)
- Verify MT4 terminal is running
- Check EA is attached to chart
- Verify firewall rules
Authentication Failed
- Check AUTH_TOKEN matches in .env files
- Verify token format (Bearer prefix)
Trade Rejected
- Check margin availability
- Verify symbol is available
- Check market is open
Timeout Errors
- Increase REQUEST_TIMEOUT
- Check network latency
- Verify EA is responding

Health Check Commands

# 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

14 KiB Raw Permalink Blame History