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

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

**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 <token>
```

**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 <token>
```

**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 <token>
```

**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 <token>
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 <token>
```

**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 <token>
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: '<bearer_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*