---
id: "ROADMAP-MT4"
title: "Roadmap de Implementacion MT4 Gateway"
type: "Roadmap"
project: "trading-platform"
epic: "OQI-010"
version: "0.1.0"
created_date: "2026-01-28"
updated_date: "2026-01-28"
---

# ROADMAP: MT4 Gateway Implementation

> **Nota:** Este roadmap es un plan propuesto. La implementacion esta
> actualmente PAUSADA y requiere decision de prioridad antes de iniciar.

---

## Vision General

Implementar una integracion completa con MetaTrader 4 que permita:
1. Consultar informacion de cuenta y posiciones
2. Obtener cotizaciones en tiempo real
3. Ejecutar operaciones de trading (buy/sell)
4. Gestionar posiciones (modificar SL/TP, cerrar)
5. Integracion con agentes LLM via MCP

---

## Fases de Implementacion

### Fase 0: Preparacion del Ambiente (1 semana)

**Objetivo:** Establecer el ambiente de desarrollo necesario

| Tarea | Prioridad | Esfuerzo | Responsable |
|-------|-----------|----------|-------------|
| Instalar MT4 Terminal en maquina de desarrollo | P0 | 1 dia | - |
| Crear cuenta demo con broker compatible | P0 | 1 dia | - |
| Configurar MetaEditor para desarrollo MQL4 | P0 | 0.5 dias | - |
| Documentar proceso de setup | P1 | 0.5 dias | - |
| Crear Docker container para gateway (opcional) | P2 | 2 dias | - |

**Entregables:**
- [ ] MT4 instalado y conectado a cuenta demo
- [ ] MetaEditor funcional
- [ ] Credenciales de cuenta demo documentadas (seguras)

**Brokers recomendados para cuenta demo:**
- IC Markets (bajo spread, MT4 estable)
- Pepperstone
- OANDA
- FXCM

---

### Fase 1: MT4 Gateway Service (2-3 semanas)

**Objetivo:** Implementar el servicio intermediario entre MCP y MT4

#### Semana 1: Core del Gateway

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Crear proyecto Node.js/TypeScript | P0 | 0.5 dias |
| Implementar servidor HTTP/REST | P0 | 1 dia |
| Definir API endpoints | P0 | 1 dia |
| Implementar autenticacion por token | P0 | 1 dia |
| Crear estructura de comandos | P0 | 1 dia |

**API Endpoints propuestos:**
```
POST /api/v1/auth/login
GET  /api/v1/account
GET  /api/v1/positions
GET  /api/v1/quote/:symbol
POST /api/v1/orders
DELETE /api/v1/orders/:ticket
PATCH /api/v1/positions/:ticket
GET  /api/v1/history
WS   /ws/stream
```

#### Semana 2: Comunicacion con EA

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Disenar protocolo de comunicacion EA-Gateway | P0 | 1 dia |
| Implementar socket server para EA | P0 | 2 dias |
| Implementar command queue | P0 | 1 dia |
| Manejar respuestas asincronas | P0 | 1 dia |

**Protocolo propuesto (JSON sobre TCP):**
```json
// Request (Gateway -> EA)
{
  "id": "uuid",
  "command": "EXECUTE_TRADE",
  "params": {
    "symbol": "XAUUSD",
    "action": "BUY",
    "lots": 0.1,
    "sl": 2640,
    "tp": 2680
  }
}

// Response (EA -> Gateway)
{
  "id": "uuid",
  "success": true,
  "ticket": 12345678,
  "data": {
    "openPrice": 2650.50,
    "openTime": "2026-01-28T10:30:00Z"
  }
}
```

#### Semana 3: Testing y Hardening

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Unit tests para gateway | P0 | 2 dias |
| Integration tests con mocks | P0 | 1 dia |
| Error handling robusto | P0 | 1 dia |
| Logging y monitoring | P1 | 1 dia |

**Entregables Fase 1:**
- [ ] Servicio gateway funcional en puerto 8081
- [ ] API REST documentada
- [ ] Socket server para comunicacion con EA
- [ ] Tests con cobertura >70%

---

### Fase 2: Expert Advisor (EA) (2-3 semanas)

**Objetivo:** Desarrollar el Expert Advisor que ejecutara operaciones en MT4

#### Semana 1: EA Base

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Crear estructura base del EA | P0 | 1 dia |
| Implementar cliente socket | P0 | 2 dias |
| Parsear comandos JSON | P0 | 1 dia |
| Implementar heartbeat | P0 | 1 dia |

**Estructura del EA:**
```
MT4BridgeEA/
├── MT4BridgeEA.mq4       # EA principal
├── SocketLib.mqh         # Libreria de socket
├── JsonParser.mqh        # Parser JSON
├── CommandHandler.mqh    # Manejador de comandos
└── README.md             # Documentacion
```

#### Semana 2: Operaciones de Trading

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Implementar OrderSend (market) | P0 | 1 dia |
| Implementar OrderSend (pending) | P0 | 1 dia |
| Implementar OrderModify | P0 | 1 dia |
| Implementar OrderClose | P0 | 1 dia |
| Manejar errores MT4 | P0 | 1 dia |

**Codigos de error MT4 a manejar:**
- ERR_NO_ERROR (0)
- ERR_COMMON_ERROR (2)
- ERR_INVALID_TRADE_PARAMETERS (3)
- ERR_SERVER_BUSY (4)
- ERR_OLD_VERSION (5)
- ERR_NO_CONNECTION (6)
- ERR_NOT_ENOUGH_MONEY (134)
- ERR_TRADE_TOO_MANY_ORDERS (148)

#### Semana 3: Reporting y Reconexion

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Implementar AccountInfo | P0 | 0.5 dias |
| Implementar PositionList | P0 | 0.5 dias |
| Implementar QuoteStream | P1 | 1 dia |
| Implementar auto-reconexion | P0 | 1 dia |
| Testing manual en cuenta demo | P0 | 2 dias |

**Entregables Fase 2:**
- [ ] Expert Advisor instalable en MT4
- [ ] Todas las operaciones de trading funcionales
- [ ] Auto-reconexion implementada
- [ ] Documentacion de instalacion

---

### Fase 3: Integracion MCP (1-2 semanas)

**Objetivo:** Conectar el mcp-mt4-connector existente con el gateway real

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Actualizar mt4-client.ts para gateway real | P0 | 1 dia |
| Implementar manejo de errores completo | P0 | 1 dia |
| Agregar retry logic | P0 | 0.5 dias |
| Agregar timeout handling | P0 | 0.5 dias |
| Tests de integracion E2E | P0 | 2 dias |
| Documentar configuracion | P1 | 0.5 dias |

**Entregables Fase 3:**
- [ ] mcp-mt4-connector conectado a gateway real
- [ ] Todos los tools funcionales con MT4 real
- [ ] Tests E2E pasando

---

### Fase 4: Paper Trading Mode (1 semana)

**Objetivo:** Implementar modo de simulacion para pruebas seguras

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Disenar modo paper trading | P0 | 0.5 dias |
| Implementar balance virtual | P0 | 1 dia |
| Simular ejecucion de ordenes | P0 | 1 dia |
| Tracking de P&L virtual | P0 | 1 dia |
| Switch entre paper/real | P0 | 0.5 dias |

**Entregables Fase 4:**
- [ ] Modo paper trading funcional
- [ ] Flag de configuracion para activar
- [ ] Metricas de paper trading

---

### Fase 5: Productionization (1-2 semanas)

**Objetivo:** Preparar para uso en produccion

| Tarea | Prioridad | Esfuerzo |
|-------|-----------|----------|
| Implementar rate limiting | P0 | 1 dia |
| Agregar risk limits | P0 | 1 dia |
| Implementar circuit breaker | P0 | 1 dia |
| Configurar alertas | P1 | 1 dia |
| Documentacion de operaciones | P1 | 1 dia |
| Runbook para incidentes | P1 | 1 dia |

**Risk Limits propuestos:**
- Max posiciones abiertas: 5
- Max lots por orden: 1.0
- Max drawdown diario: 5%
- Cooldown entre trades: 60 segundos

**Entregables Fase 5:**
- [ ] Rate limiting configurado
- [ ] Risk limits implementados
- [ ] Circuit breaker funcional
- [ ] Documentacion de operaciones

---

## Timeline Estimado

```
Fase 0: Preparacion     |====|                                    (1 sem)
Fase 1: MT4 Gateway          |============|                       (3 sem)
Fase 2: Expert Advisor                     |============|         (3 sem)
Fase 3: Integracion MCP                                 |====|    (1.5 sem)
Fase 4: Paper Trading                                       |===| (1 sem)
Fase 5: Production                                            |===| (1.5 sem)
                        |----|----|----|----|----|----|----|----|----|----|
                        S1   S2   S3   S4   S5   S6   S7   S8   S9   S10  S11

Total estimado: 10-11 semanas
```

---

## Recursos Requeridos

### Personal
- 1 Desarrollador Senior (TypeScript + MQL4)
- 0.5 QA Engineer (testing)

### Infraestructura
- Maquina Windows para MT4 (o VM)
- Cuenta demo con broker
- CI/CD para gateway

### Dependencias Externas
- Broker MT4 (cuenta demo gratuita)
- Documentacion MQL4 (gratis)

---

## Criterios de Exito

| Metrica | Target | Medicion |
|---------|--------|----------|
| Latencia de ejecucion | <500ms | Promedio en paper trading |
| Uptime del gateway | >99% | Monitoring |
| Precision de ordenes | 100% | Ordenes ejecutadas vs solicitadas |
| Cobertura de tests | >70% | Jest/pytest coverage |

---

## Riesgos y Mitigaciones

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Complejidad MQL4 | Alta | Alto | Documentacion, pruebas incrementales |
| Latencia alta | Media | Medio | Optimizar comunicacion, caché |
| Desconexiones | Media | Alto | Auto-reconnect, alertas |
| Errores de trading | Alta | Critico | Paper trading obligatorio primero |

---

## Decision Gates

### Gate 1: Fin de Fase 1
- [ ] Gateway responde a requests
- [ ] Socket server acepta conexiones
- [ ] Tests unitarios pasan

### Gate 2: Fin de Fase 2
- [ ] EA se conecta al gateway
- [ ] Operaciones basicas funcionan en demo
- [ ] Reconexion automatica funciona

### Gate 3: Fin de Fase 3
- [ ] MCP tools ejecutan trades reales
- [ ] E2E tests pasan
- [ ] Documentacion completa

### Gate 4: Ready for Production
- [ ] Paper trading validado
- [ ] Risk limits funcionando
- [ ] Runbook creado

---

## Proximos Pasos Inmediatos

Si se decide priorizar esta epica:

1. **Semana 1:**
   - Asignar desarrollador responsable
   - Setup ambiente de desarrollo
   - Crear cuenta demo con broker

2. **Semana 2:**
   - Iniciar desarrollo del gateway
   - Kick-off de arquitectura detallada

---

*Este roadmap sera actualizado conforme avance la implementacion.*
*Ultima actualizacion: 2026-01-28*