trading-platform/docs/02-definicion-modulos/OQI-011-mt4-gateway/especificaciones/ET-MT4-001-gateway.md

id	title	type	project	epic	version	created_date	updated_date	status
ET-MT4-001	Especificacion Tecnica: MT4 Gateway Service	Technical Specification	trading-platform	OQI-010	0.1.0	2026-01-28	2026-01-28	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.

Authorization: Bearer <token>

Token de desarrollo: Configurar en .env

4.3 Endpoints

4.3.1 Health Check

GET /health

Response:

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

GET /api/v1/account
Authorization: Bearer <token>

Response:

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

GET /api/v1/positions
Authorization: Bearer <token>

Query Parameters:

Param	Type	Required	Description
symbol	string	No	Filtrar por simbolo

Response:

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

GET /api/v1/quote/:symbol
Authorization: Bearer <token>

Response:

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

POST /api/v1/orders
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

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

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

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

DELETE /api/v1/orders/:ticket
Authorization: Bearer <token>

Response:

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

PATCH /api/v1/positions/:ticket
Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "stopLoss": 2645.00,
  "takeProfit": 2685.00
}

Response:

{
  "success": true,
  "data": {
    "ticket": 12345678,
    "stopLoss": 2645.00,
    "takeProfit": 2685.00,
    "modifiedTime": "2026-01-28T10:15:00Z"
  }
}

---

5. WebSocket API

5.1 Connection

const ws = new WebSocket('ws://localhost:8081/ws/stream');
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: '<bearer_token>'
  }));
};

5.2 Subscribe to Quotes

// 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

// 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

// EA -> Gateway
{
  "type": "handshake",
  "version": "1.0",
  "accountLogin": 12345678
}

// Gateway -> EA
{
  "type": "handshake_ack",
  "status": "connected",
  "sessionId": "uuid"
}

6.3 Heartbeat

// Cada 5 segundos
// EA -> Gateway
{
  "type": "heartbeat",
  "timestamp": 1706436000
}

// Gateway -> EA
{
  "type": "heartbeat_ack"
}

6.4 Command Format

// 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

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

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)

{
  "name": "mt4-gateway",
  "script": "dist/index.js",
  "instances": 1,
  "autorestart": true,
  "max_memory_restart": "500M"
}

---

13. Referencias

• README.md - Vision general
• STATUS.md - Estado actual
• ROADMAP-MT4.md - Plan de implementacion
• MCP MT4 Connector
• MCP Protocol
• MetaTrader 4 Documentation

---

Documento creado: 2026-01-28 Estado: DRAFT - Pendiente implementacion