--- id: "ET-MT4-001" title: "Especificacion Tecnica: MT4 Gateway Service" type: "Technical Specification" project: "trading-platform" epic: "OQI-010" version: "0.1.0" created_date: "2026-01-28" updated_date: "2026-01-28" status: "DRAFT" --- # ET-MT4-001: MT4 Gateway Service ## 1. Resumen Esta especificacion define los requisitos tecnicos para el servicio MT4 Gateway, el componente intermedio que conecta el MCP MT4 Connector con el Expert Advisor ejecutandose en MetaTrader 4. --- ## 2. Alcance ### 2.1 Incluido - API REST para comunicacion con MCP Connector - WebSocket server para streaming de datos - Socket server para comunicacion con Expert Advisor - Autenticacion y autorizacion - Queue de comandos - Logging y monitoring ### 2.2 Excluido - Desarrollo del Expert Advisor (ver ET-MT4-002) - Logica de trading/estrategia - Interfaz de usuario --- ## 3. Arquitectura ### 3.1 Diagrama de Componentes ``` ┌─────────────────────────────────────────────────────────────────┐ │ MT4 GATEWAY SERVICE │ │ (Node.js/TypeScript) │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────┐ ┌───────────────────┐ │ │ │ HTTP/REST API │ │ WebSocket Server │ │ │ │ (Express.js) │ │ (ws library) │ │ │ │ │ │ │ │ │ │ Port: 8081 │ │ Path: /ws/* │ │ │ └─────────┬─────────┘ └─────────┬─────────┘ │ │ │ │ │ │ └───────────┬────────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ Command Processor │ │ │ │ │ │ │ │ - Request Validation │ │ │ │ - Rate Limiting │ │ │ │ - Auth Verification │ │ │ └───────────┬───────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ Command Queue │ │ │ │ │ │ │ │ - Priority Queue │ │ │ │ - Timeout Handling │ │ │ │ - Retry Logic │ │ │ └───────────┬───────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ EA Socket Server │ │ │ │ │ │ │ │ Port: 8082 │ │ │ │ Protocol: TCP/JSON │ │ │ └───────────┬───────────┘ │ │ │ │ └────────────────────────┼────────────────────────────────────────┘ │ ▼ ┌─────────────────────┐ │ Expert Advisor │ │ (MT4 Terminal) │ └─────────────────────┘ ``` ### 3.2 Stack Tecnologico | Componente | Tecnologia | Version | |------------|------------|---------| | Runtime | Node.js | >= 20.x | | Language | TypeScript | >= 5.0 | | HTTP Server | Express.js | >= 4.18 | | WebSocket | ws | >= 8.x | | Validation | Zod | >= 3.x | | Logging | Winston | >= 3.x | | Testing | Jest | >= 29.x | --- ## 4. API REST ### 4.1 Base URL ``` http://localhost:8081/api/v1 ``` ### 4.2 Autenticacion Todas las rutas (excepto `/health`) requieren autenticacion via Bearer token. ```http Authorization: Bearer ``` **Token de desarrollo:** Configurar en `.env` ### 4.3 Endpoints #### 4.3.1 Health Check ```http GET /health ``` **Response:** ```json { "status": "ok", "service": "mt4-gateway", "version": "0.1.0", "timestamp": "2026-01-28T10:00:00Z", "dependencies": { "ea": "connected", "mt4": "connected" } } ``` #### 4.3.2 Account Info ```http GET /api/v1/account Authorization: Bearer ``` **Response:** ```json { "success": true, "data": { "login": 12345678, "name": "Demo Account", "server": "ICMarkets-Demo", "currency": "USD", "balance": 10000.00, "equity": 10250.50, "margin": 500.00, "freeMargin": 9750.50, "marginLevel": 2050.10, "leverage": 100 } } ``` #### 4.3.3 Positions ```http GET /api/v1/positions Authorization: Bearer ``` **Query Parameters:** | Param | Type | Required | Description | |-------|------|----------|-------------| | symbol | string | No | Filtrar por simbolo | **Response:** ```json { "success": true, "data": { "positions": [ { "ticket": 12345678, "symbol": "XAUUSD", "type": "buy", "lots": 0.10, "openPrice": 2650.50, "currentPrice": 2655.00, "stopLoss": 2640.00, "takeProfit": 2680.00, "profit": 45.00, "swap": -2.50, "commission": -5.00, "openTime": "2026-01-28T08:00:00Z", "comment": "MCP Trade" } ], "count": 1 } } ``` #### 4.3.4 Quote ```http GET /api/v1/quote/:symbol Authorization: Bearer ``` **Response:** ```json { "success": true, "data": { "symbol": "XAUUSD", "bid": 2654.50, "ask": 2655.00, "spread": 0.50, "time": "2026-01-28T10:00:00Z", "digits": 2 } } ``` #### 4.3.5 Execute Order ```http POST /api/v1/orders Authorization: Bearer Content-Type: application/json ``` **Request Body:** ```json { "symbol": "XAUUSD", "action": "buy", "lots": 0.10, "type": "market", "stopLoss": 2640.00, "takeProfit": 2680.00, "comment": "MCP Trade", "magicNumber": 12345 } ``` **Parameters:** | Field | Type | Required | Description | |-------|------|----------|-------------| | symbol | string | Yes | Trading symbol | | action | enum | Yes | "buy" or "sell" | | lots | number | Yes | Lot size (0.01 - 10.0) | | type | enum | Yes | "market", "limit", "stop" | | price | number | No* | Price for limit/stop orders | | stopLoss | number | No | Stop loss price | | takeProfit | number | No | Take profit price | | comment | string | No | Order comment | | magicNumber | number | No | Magic number for EA | **Response (Success):** ```json { "success": true, "data": { "ticket": 12345679, "symbol": "XAUUSD", "action": "buy", "lots": 0.10, "openPrice": 2655.00, "openTime": "2026-01-28T10:00:05Z", "stopLoss": 2640.00, "takeProfit": 2680.00 } } ``` **Response (Error):** ```json { "success": false, "error": { "code": "INSUFFICIENT_MARGIN", "message": "Not enough free margin to open position", "details": { "required": 2500.00, "available": 1000.00 } } } ``` #### 4.3.6 Close Position ```http DELETE /api/v1/orders/:ticket Authorization: Bearer ``` **Response:** ```json { "success": true, "data": { "ticket": 12345678, "closePrice": 2660.00, "closeTime": "2026-01-28T10:30:00Z", "profit": 95.00, "swap": -2.50, "commission": -5.00 } } ``` #### 4.3.7 Modify Position ```http PATCH /api/v1/positions/:ticket Authorization: Bearer Content-Type: application/json ``` **Request Body:** ```json { "stopLoss": 2645.00, "takeProfit": 2685.00 } ``` **Response:** ```json { "success": true, "data": { "ticket": 12345678, "stopLoss": 2645.00, "takeProfit": 2685.00, "modifiedTime": "2026-01-28T10:15:00Z" } } ``` --- ## 5. WebSocket API ### 5.1 Connection ```javascript const ws = new WebSocket('ws://localhost:8081/ws/stream'); ws.onopen = () => { ws.send(JSON.stringify({ type: 'auth', token: '' })); }; ``` ### 5.2 Subscribe to Quotes ```json // Request { "type": "subscribe", "channel": "quotes", "symbols": ["XAUUSD", "EURUSD"] } // Response (streaming) { "type": "quote", "data": { "symbol": "XAUUSD", "bid": 2654.55, "ask": 2655.05, "time": "2026-01-28T10:00:01Z" } } ``` ### 5.3 Subscribe to Positions ```json // Request { "type": "subscribe", "channel": "positions" } // Response (on change) { "type": "position_update", "data": { "ticket": 12345678, "profit": 50.00, "currentPrice": 2656.00 } } ``` --- ## 6. EA Communication Protocol ### 6.1 TCP Socket - **Puerto:** 8082 - **Protocolo:** TCP - **Formato:** JSON delimitado por newline ### 6.2 Handshake ```json // EA -> Gateway { "type": "handshake", "version": "1.0", "accountLogin": 12345678 } // Gateway -> EA { "type": "handshake_ack", "status": "connected", "sessionId": "uuid" } ``` ### 6.3 Heartbeat ```json // Cada 5 segundos // EA -> Gateway { "type": "heartbeat", "timestamp": 1706436000 } // Gateway -> EA { "type": "heartbeat_ack" } ``` ### 6.4 Command Format ```json // Gateway -> EA (Request) { "id": "uuid-request-id", "type": "command", "command": "EXECUTE_ORDER", "params": { "symbol": "XAUUSD", "action": "OP_BUY", "lots": 0.10, "stopLoss": 2640.00, "takeProfit": 2680.00 }, "timeout": 30000 } // EA -> Gateway (Response) { "id": "uuid-request-id", "type": "response", "success": true, "data": { "ticket": 12345679, "openPrice": 2655.00 } } // EA -> Gateway (Error) { "id": "uuid-request-id", "type": "response", "success": false, "error": { "code": 134, "message": "ERR_NOT_ENOUGH_MONEY" } } ``` ### 6.5 Commands Supported | Command | Description | Params | |---------|-------------|--------| | GET_ACCOUNT | Get account info | - | | GET_POSITIONS | List open positions | symbol? | | GET_QUOTE | Get current quote | symbol | | EXECUTE_ORDER | Execute trade | symbol, action, lots, ... | | CLOSE_ORDER | Close position | ticket | | MODIFY_ORDER | Modify SL/TP | ticket, sl?, tp? | --- ## 7. Error Codes ### 7.1 Gateway Errors | Code | HTTP | Description | |------|------|-------------| | AUTH_FAILED | 401 | Invalid or missing token | | FORBIDDEN | 403 | Insufficient permissions | | NOT_FOUND | 404 | Resource not found | | VALIDATION_ERROR | 400 | Invalid request parameters | | EA_DISCONNECTED | 503 | EA not connected | | MT4_ERROR | 502 | MT4 returned error | | TIMEOUT | 504 | Request timeout | | RATE_LIMITED | 429 | Too many requests | ### 7.2 MT4 Error Mapping | MT4 Code | Gateway Code | Description | |----------|--------------|-------------| | 0 | - | Success | | 2 | MT4_COMMON_ERROR | Common error | | 3 | MT4_INVALID_PARAMS | Invalid trade parameters | | 4 | MT4_SERVER_BUSY | Server busy | | 6 | MT4_NO_CONNECTION | No connection | | 134 | INSUFFICIENT_MARGIN | Not enough margin | | 148 | MT4_TOO_MANY_ORDERS | Too many orders | --- ## 8. Security Requirements ### 8.1 Authentication - Bearer token authentication - Token rotation each 24 hours - Rate limiting per token ### 8.2 Rate Limiting | Endpoint | Limit | Window | |----------|-------|--------| | GET /account | 60 | 1 min | | GET /positions | 60 | 1 min | | GET /quote | 120 | 1 min | | POST /orders | 10 | 1 min | | DELETE /orders | 10 | 1 min | | PATCH /positions | 20 | 1 min | ### 8.3 Input Validation - All inputs validated with Zod schemas - SQL injection protection (N/A, no SQL) - Symbol whitelist validation ### 8.4 Logging - All requests logged with timestamp - All trades logged for audit - No sensitive data in logs (tokens masked) --- ## 9. Configuration ### 9.1 Environment Variables ```env # Server PORT=8081 EA_SOCKET_PORT=8082 NODE_ENV=development # Auth AUTH_TOKEN=your-secret-token TOKEN_EXPIRY_HOURS=24 # EA Connection EA_HEARTBEAT_INTERVAL=5000 EA_RECONNECT_DELAY=5000 EA_MAX_RECONNECT_ATTEMPTS=10 # Timeouts REQUEST_TIMEOUT=30000 EA_COMMAND_TIMEOUT=30000 # Rate Limiting RATE_LIMIT_WINDOW_MS=60000 RATE_LIMIT_MAX_REQUESTS=60 # Logging LOG_LEVEL=info LOG_FILE=./logs/gateway.log # Risk Limits MAX_LOTS_PER_ORDER=1.0 MAX_OPEN_POSITIONS=5 MIN_FREE_MARGIN_PERCENT=50 ``` --- ## 10. Monitoring ### 10.1 Health Metrics - Gateway uptime - EA connection status - Request latency (p50, p95, p99) - Error rate - Active WebSocket connections ### 10.2 Trading Metrics - Orders executed - Orders failed - Average execution time - P&L tracking ### 10.3 Alerts - EA disconnection - High error rate (>5%) - High latency (>5s) - Risk limit breach --- ## 11. Testing Requirements ### 11.1 Unit Tests - Command processor - Validation schemas - Error handling - Rate limiting ### 11.2 Integration Tests - EA mock communication - Full request flow - WebSocket subscriptions ### 11.3 E2E Tests (with demo account) - Order execution - Position modification - Account queries **Coverage Target:** >70% --- ## 12. Deployment ### 12.1 Docker (Recomendado) ```dockerfile FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY dist ./dist EXPOSE 8081 8082 CMD ["node", "dist/index.js"] ``` ### 12.2 PM2 (Alternativo) ```json { "name": "mt4-gateway", "script": "dist/index.js", "instances": 1, "autorestart": true, "max_memory_restart": "500M" } ``` --- ## 13. Referencias - [README.md](../README.md) - Vision general - [STATUS.md](../STATUS.md) - Estado actual - [ROADMAP-MT4.md](../ROADMAP-MT4.md) - Plan de implementacion - [MCP MT4 Connector](../../../../mcp-mt4-connector/README.md) - [MCP Protocol](https://modelcontextprotocol.io) - [MetaTrader 4 Documentation](https://www.mql4.com/docs) --- *Documento creado: 2026-01-28* *Estado: DRAFT - Pendiente implementacion*