trading-platform/docs/02-definicion-modulos/OQI-011-mt4-gateway/ROADMAP-MT4.md

id	title	type	project	epic	version	created_date	updated_date
ROADMAP-MT4	Roadmap de Implementacion MT4 Gateway	Roadmap	trading-platform	OQI-010	0.1.0	2026-01-28	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):

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