rckrdmrd/trading-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
trading-platform/docs/90-transversal/integraciones/INT-MT4-001-gateway-service.md
rckrdmrd c1b5081208 feat(ml): Complete FASE 11 - BTCUSD update and comprehensive documentation alignment 
ML Engine Updates:
- Updated BTCUSD with Polygon API data (2024-2025): 215,699 new records
- Re-trained all ML models: Attention (R²: 0.223), Base, Metamodel (87.3% confidence)
- Backtest results: +176.71R profit with aggressive_filter strategy

Documentation Consolidation:
- Created docs/99-analisis/_MAP.md index with 13 new analysis documents
- Consolidated inventories: removed duplicates from orchestration/inventarios/
- Updated ML_INVENTORY.yml with BTCUSD metrics and training results
- Added execution reports: FASE11-BTCUSD, correction issues, alignment validation

Architecture & Integration:
- Updated all module documentation with NEXUS v3.4 frontmatter
- Fixed _MAP.md indexes across all folders
- Updated orchestration plans and traces

Files: 229 changed, 5064 insertions(+), 1872 deletions(-)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 09:31:29 -06:00

463 lines
18 KiB
Markdown
Raw Permalink Blame History

---
id: "INT-MT4-001-gateway-service"
title: "MT4 Gateway Service - Integración Multi-Agente"
type: "Documentation"
project: "trading-platform"
version: "1.0.0"
updated_date: "2026-01-04"
---
# INT-MT4-001: MT4 Gateway Service - Integración Multi-Agente
## Metadata
| Campo | Valor |
|-------|-------|
| **ID** | INT-MT4-001 |
| **Módulo** | MT4 Gateway Service |
| **Tipo** | Especificación de Integración |
| **Versión** | 1.0.0 |
| **Estado** | En Desarrollo |
| **Fecha creación** | 2025-12-12 |
| **Última actualización** | 2025-12-12 |
| **Autor** | Architecture-Analyst |
| **Épica relacionada** | OQI-009 |
---
## 1. Resumen Ejecutivo
El **MT4 Gateway Service** es un componente crítico que permite:
- Gestión de **múltiples cuentas MT4** de forma independiente
- Cada cuenta con su propio **agente de trading** (Atlas, Orion, Nova)
- **API unificada** para interactuar con todas las cuentas
- **Risk management** por agente
- Integración con el **ML Engine** para ejecución de señales
---
## 2. Arquitectura de la Integración
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ORBIQUANT TRADING PLATFORM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Admin │ │ Backend │ │ ML Engine │ │ LLM Agent │ │
│ │ Dashboard │ │ Express │ │ FastAPI │ │ (Future) │ │
│ │ :5173 │ │ :3001 │ │ :8000 │ │ :8002 │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └─────────────────┴─────────────────┴─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ MT4 GATEWAY SERVICE (:8090) │ │
│ │ │ │
│ │ /api/agents - Lista agentes │ │
│ │ /api/agents/summary - Resumen consolidado │ │
│ │ /api/agents/{id}/trade - Ejecutar trade │ │
│ │ /api/agents/{id}/account - Info de cuenta │ │
│ │ /api/emergency/stop-all - Parada de emergencia │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Agent Registry │ │ │
│ │ │ │ │ │
│ │ │ agent_1 (Atlas) → MT4 Bridge @ :8081 → Account 22437 │ │ │
│ │ │ agent_2 (Orion) → MT4 Bridge @ :8082 → Account XXXXX │ │ │
│ │ │ agent_3 (Nova) → MT4 Bridge @ :8083 → Account YYYYY │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ MT4 │ │ MT4 │ │ MT4 │ │
│ │ Terminal │ │ Terminal │ │ Terminal │ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │
│ │ │ │ │ │ │ │
│ │ EA Bridge │ │ EA Bridge │ │ EA Bridge │ │
│ │ :8081 │ │ :8082 │ │ :8083 │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └─────────────────────────┴─────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ EBC Financial Group (Broker) │ │
│ │ Server: EBCFinancialGroupKY-Demo02 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 3. Componentes del Sistema
### 3.1 MT4 Gateway Service
| Atributo | Valor |
|----------|-------|
| **Ubicación** | `apps/mt4-gateway/` |
| **Framework** | Python/FastAPI |
| **Puerto** | 8090 |
| **Inventario** | `docs/90-transversal/inventarios/MT4_GATEWAY_INVENTORY.yml` |
#### Archivos Principales
| Archivo | Propósito | Líneas |
|---------|-----------|--------|
| `src/main.py` | Aplicación FastAPI principal | ~400 |
| `src/providers/mt4_bridge_client.py` | Cliente para EA Bridge | ~350 |
| `config/agents.yml` | Configuración de agentes | ~150 |
| `requirements.txt` | Dependencias Python | ~25 |
### 3.2 Agentes de Trading
| ID | Nombre | Puerto | Strategy | Pares | Risk | Estado |
|----|--------|--------|----------|-------|------|--------|
| agent_1 | Atlas | 8081 | AMD | XAUUSD | 1% | Enabled |
| agent_2 | Orion | 8082 | ICT | EUR/GBP | 1.5% | Disabled |
| agent_3 | Nova | 8083 | Mixed | ALL | 2% | Disabled |
### 3.3 EA Bridge (por terminal MT4)
Cada terminal MT4 requiere un Expert Advisor (EA) que expone una API REST.
| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/account` | GET | Información de cuenta |
| `/tick/{symbol}` | GET | Precio actual |
| `/positions` | GET | Posiciones abiertas |
| `/trade` | POST | Ejecutar operación |
| `/history` | GET | Historial de trades |
---
## 4. Flujo de Datos
### 4.1 Flujo de Señal → Ejecución
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ML Engine │────▶│ Gateway │────▶│Risk Manager │────▶│ MT4 Client │
│ │ │ Service │ │ │ │ │
│ Signal: │ │ │ │ Validates: │ │ Executes: │
│ • XAUUSD │ │ Routes to: │ │ • Max risk │ │ • OpenOrder │
│ • LONG │ │ • agent_1 │ │ • Position │ │ • SL/TP │
│ • Conf: 78% │ │ • agent_3 │ │ • Daily DD │ │ • Logging │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ MT4 │
│ Terminal │
│ + EA │
└─────────────┘
```
### 4.2 Flujo de Datos de Cuenta
```
Frontend (Dashboard)
│
▼
GET /api/agents/summary
│
▼
MT4 Gateway Service
│
├───▶ Agent 1: GET /account → MT4 Terminal 1
├───▶ Agent 2: GET /account → MT4 Terminal 2
└───▶ Agent 3: GET /account → MT4 Terminal 3
│
▼
Consolidate Response
│
▼
{
total_balance: 1700,
total_equity: 1720,
total_profit: 45.30,
agents: [...]
}
```
---
## 5. Matriz de Trazabilidad
### 5.1 Dependencias de Componentes
| Componente Origen | Componente Destino | Tipo | Protocolo | Estado |
|-------------------|-------------------|------|-----------|--------|
| Admin Dashboard | MT4 Gateway | Consumer | HTTP REST | Pendiente |
| Backend Express | MT4 Gateway | Consumer | HTTP REST | Pendiente |
| ML Engine | MT4 Gateway | Provider | HTTP REST | Pendiente |
| MT4 Gateway | MT4 Terminal 1 | Consumer | HTTP REST | Ready |
| MT4 Gateway | MT4 Terminal 2 | Consumer | HTTP REST | Ready |
| MT4 Gateway | MT4 Terminal 3 | Consumer | HTTP REST | Ready |
| MT4 Gateway | PostgreSQL | Consumer | TCP | Pendiente |
### 5.2 Relación con Épicas
| Épica | Relación | Descripción |
|-------|----------|-------------|
| OQI-003 | Consumer | Trading Charts consume datos de posiciones |
| OQI-004 | Integration | Investment Accounts integra con agentes |
| OQI-006 | Provider | ML Signals provee señales a ejecutar |
| OQI-007 | Integration | LLM Agent puede ejecutar via Gateway |
| OQI-008 | Integration | Portfolio Manager consolida agentes |
| **OQI-009** | **Owner** | **Épica principal del MT4 Gateway** |
### 5.3 Archivos Relacionados
| Archivo | Tipo | Relación |
|---------|------|----------|
| `apps/mt4-gateway/src/main.py` | Source | Implementación principal |
| `apps/mt4-gateway/config/agents.yml` | Config | Configuración de agentes |
| `apps/data-service/.env` | Config | Credenciales MT4 |
| `docs/01-arquitectura/ARQUITECTURA-MULTI-AGENTE-MT4.md` | Doc | Arquitectura detallada |
| `docs/90-transversal/setup/SETUP-MT4-TRADING.md` | Doc | Guía de setup |
| `docs/90-transversal/inventarios/MT4_GATEWAY_INVENTORY.yml` | Inventory | Inventario del servicio |
---
## 6. Configuración de Risk Management
### 6.1 Por Agente
```yaml
agent_1 (Atlas):
initial_balance: $200
max_risk_per_trade: 1% # $2
max_daily_loss: 5% # $10
max_positions: 1
allowed_pairs: [XAUUSD]
agent_2 (Orion):
initial_balance: $500
max_risk_per_trade: 1.5% # $7.50
max_daily_loss: 5% # $25
max_positions: 2
allowed_pairs: [EURUSD, GBPUSD]
agent_3 (Nova):
initial_balance: $1000
max_risk_per_trade: 2% # $20
max_daily_loss: 5% # $50
max_positions: 3
allowed_pairs: [XAUUSD, EURUSD, GBPUSD, USDJPY]
```
### 6.2 Global
```yaml
emergency_stop_all: false
max_total_exposure: 10%
correlation_limit: 0.5
```
---
## 7. API Reference
### 7.1 Endpoints
| Endpoint | Método | Descripción | Auth |
|----------|--------|-------------|------|
| `/health` | GET | Health check | No |
| `/api/status` | GET | Estado detallado | No |
| `/api/agents` | GET | Lista agentes | Yes |
| `/api/agents/summary` | GET | Resumen consolidado | Yes |
| `/api/agents/{id}` | GET | Info de agente | Yes |
| `/api/agents/{id}/account` | GET | Info de cuenta MT4 | Yes |
| `/api/agents/{id}/positions` | GET | Posiciones abiertas | Yes |
| `/api/agents/{id}/tick/{symbol}` | GET | Precio actual | Yes |
| `/api/agents/{id}/trade` | POST | Ejecutar trade | Yes |
| `/api/agents/{id}/close` | POST | Cerrar posición | Yes |
| `/api/agents/{id}/modify` | POST | Modificar SL/TP | Yes |
| `/api/agents/{id}/close-all` | POST | Cerrar todas | Yes |
| `/api/emergency/stop-all` | POST | EMERGENCY stop | Admin |
### 7.2 Modelos de Request/Response
#### TradeRequest
```json
{
"symbol": "XAUUSD",
"action": "buy",
"lots": 0.01,
"sl": 2640.00,
"tp": 2660.00,
"comment": "Trading Platform-Atlas"
}
```
#### GlobalSummary Response
```json
{
"total_balance": 1700.00,
"total_equity": 1720.50,
"total_profit": 45.30,
"total_positions": 2,
"agents_online": 2,
"agents_offline": 1,
"agents": [
{
"agent_id": "agent_1",
"name": "Atlas",
"status": "online",
"balance": 200.00,
"equity": 205.50,
"profit": 5.50,
"open_positions": 1,
"strategy": "amd"
}
]
}
```
---
## 8. Impacto en el Sistema
### 8.1 Componentes Afectados
| Componente | Tipo Impacto | Acción Requerida |
|------------|--------------|------------------|
| Backend Express | Nuevo módulo | Crear `/api/trading/*` routes |
| Admin Dashboard | Nueva página | Crear página de agentes |
| ML Engine | Nuevo consumer | WebSocket para señales |
| PostgreSQL | Nuevas tablas | Tablas de trades y logs |
| Data Service | Referencia | Sin cambios |
### 8.2 Cambios en Base de Datos
```sql
-- Nuevas tablas requeridas (futuro)
CREATE TABLE trading.agent_trades (
id SERIAL PRIMARY KEY,
agent_id VARCHAR(50),
ticket INTEGER,
symbol VARCHAR(20),
action VARCHAR(10),
lots DECIMAL(10,2),
open_price DECIMAL(20,5),
close_price DECIMAL(20,5),
stop_loss DECIMAL(20,5),
take_profit DECIMAL(20,5),
profit DECIMAL(20,5),
open_time TIMESTAMP,
close_time TIMESTAMP,
signal_id INTEGER,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE trading.agent_logs (
id SERIAL PRIMARY KEY,
agent_id VARCHAR(50),
event_type VARCHAR(50),
message TEXT,
metadata JSONB,
created_at TIMESTAMP DEFAULT NOW()
);
```
---
## 9. Requisitos de Infraestructura
### 9.1 Para Ejecución Local
| Componente | Requisito |
|------------|-----------|
| Python | 3.10+ |
| MT4 Terminal | Windows (o Wine en Linux) |
| EA Bridge | Instalado en MT4 |
| PostgreSQL | 15+ |
| Redis | 7+ (opcional, para cache) |
### 9.2 Para Producción
| Componente | Requisito |
|------------|-----------|
| VPS Windows | Para terminales MT4 24/7 |
| VPS Linux | Para servicios Python |
| Supervisord | Process manager |
| Nginx | Reverse proxy |
---
## 10. Testing
### 10.1 Tests Requeridos
- [ ] `test_mt4_bridge_client.py` - Conexión con EA Bridge
- [ ] `test_gateway_endpoints.py` - Endpoints REST
- [ ] `test_risk_manager.py` - Validaciones de riesgo
- [ ] `test_trade_execution.py` - Ejecución de trades
### 10.2 Test de Integración
```bash
# Verificar gateway
curl http://localhost:8090/health
# Verificar agentes
curl http://localhost:8090/api/agents/summary
# Test trade (demo only)
curl -X POST http://localhost:8090/api/agents/agent_1/trade \
-H "Content-Type: application/json" \
-d '{"symbol":"XAUUSD","action":"buy","lots":0.01}'
```
---
## 11. Próximos Pasos
| # | Tarea | Prioridad | Dependencia |
|---|-------|-----------|-------------|
| 1 | Instalar MT4 y EA Bridge | Alta | VPS Windows |
| 2 | Test conexión Gateway → MT4 | Alta | #1 |
| 3 | Integrar con ML Engine | Alta | ML Engine WebSocket |
| 4 | Implementar Risk Manager | Alta | - |
| 5 | Crear Admin Dashboard | Media | Backend routes |
| 6 | Agregar autenticación JWT | Media | Backend auth |
| 7 | Logging a PostgreSQL | Baja | DB migrations |
---
## 12. Referencias
- [ARQUITECTURA-MULTI-AGENTE-MT4.md](../../01-arquitectura/ARQUITECTURA-MULTI-AGENTE-MT4.md)
- [SETUP-MT4-TRADING.md](../setup/SETUP-MT4-TRADING.md)
- [MT4_GATEWAY_INVENTORY.yml](../inventarios/MT4_GATEWAY_INVENTORY.yml)
- [ADR-002-MVP-OPERATIVO-TRADING.md](../../97-adr/ADR-002-MVP-OPERATIVO-TRADING.md)
- [INT-DATA-001-data-service.md](./INT-DATA-001-data-service.md)
---
## 13. Historial de Cambios
| Versión | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0.0 | 2025-12-12 | Architecture-Analyst | Creación inicial |
---
**Estado de Validación:**
| Aspecto | Estado | Notas |
|---------|--------|-------|
| Código Gateway implementado | ✅ | Estructura base completa |
| Configuración de agentes | ✅ | 3 agentes definidos |
| Documentación | ✅ | Este documento |
| Tests | ⏳ | Pendiente |
| Integración ML Engine | ⏳ | Pendiente |
| Integración Admin | ⏳ | Pendiente |
Reference in New Issue View Git Blame Copy Permalink