--- id: "RF-INV-005" title: "Agentes de Trading Automatico" type: "Requirement" status: "Done" priority: "Alta" epic: "OQI-004" project: "trading-platform" version: "1.0.0" created_date: "2025-12-05" updated_date: "2026-01-04" --- # RF-INV-005: Agentes de Trading Automático ## Metadata | Campo | Valor | |-------|-------| | **ID** | RF-INV-005 | | **Épica** | OQI-004 - Cuentas de Inversión | | **Tipo** | Requerimiento Funcional | | **Prioridad** | P0 | | **Story Points** | 13 | | **Estado** | Aprobado | | **Última actualización** | 2025-12-05 | --- ## Descripción El sistema debe implementar agentes de trading automático (Atlas, Orion, Nova) que ejecuten operaciones en nombre de los usuarios, siguiendo estrategias predefinidas y utilizando señales del ML Engine. --- ## Arquitectura de Agentes ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ AGENT ORCHESTRATOR │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Signal Receiver │ │ │ │ (Consume signals from ML Engine) │ │ │ └───────────────────────────┬─────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────▼─────────────────────────────────────┐ │ │ │ Strategy Router │ │ │ │ (Route signals to appropriate agent type) │ │ │ └─────────┬───────────────────┬───────────────────┬───────────────┘ │ │ │ │ │ │ │ ┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐ │ │ │ ATLAS │ │ ORION │ │ NOVA │ │ │ │ (Conservative)│ │ (Moderate) │ │ (Aggressive) │ │ │ │ │ │ │ │ │ │ │ │ • Mean Rev. │ │ • Trend │ │ • Momentum │ │ │ │ • Grid │ │ • Breakout │ │ • Altcoin Rot │ │ │ │ • Low Risk │ │ • Med Risk │ │ • High Risk │ │ │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ │ │ │ │ ┌─────────▼───────────────────▼───────────────────▼───────────────┐ │ │ │ Position Manager │ │ │ │ (Manage positions across accounts) │ │ │ └───────────────────────────┬─────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────▼─────────────────────────────────────┐ │ │ │ Order Executor │ │ │ │ (Execute on Exchange) │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## Estrategias por Agente ### Atlas (Conservador) ```typescript interface AtlasStrategy { name: 'atlas'; // Trading parameters maxPositionSize: 0.05; // 5% del balance por posición maxOpenPositions: 3; stopLossPercent: 0.5; // 0.5% stop loss takeProfitPercent: 1.0; // 1% take profit // Entry conditions entrySignalMinConfidence: 0.75; // Asset allocation allowedAssets: ['BTCUSDT', 'ETHUSDT']; // Risk management maxDailyDrawdown: 1.0; // Pausar si pierde 1% en el día maxTotalDrawdown: 5.0; // Pausar si pierde 5% desde máximo // Strategy types strategies: ['mean_reversion', 'grid_trading']; } ``` ### Orion (Moderado) ```typescript interface OrionStrategy { name: 'orion'; // Trading parameters maxPositionSize: 0.10; // 10% del balance por posición maxOpenPositions: 5; stopLossPercent: 1.0; takeProfitPercent: 2.0; // Entry conditions entrySignalMinConfidence: 0.65; // Asset allocation allowedAssets: [ 'BTCUSDT', 'ETHUSDT', 'BNBUSDT', 'SOLUSDT', 'XRPUSDT', 'ADAUSDT', 'AVAXUSDT', 'DOTUSDT', 'MATICUSDT', 'LINKUSDT' ]; // Risk management maxDailyDrawdown: 2.0; maxTotalDrawdown: 10.0; // Strategy types strategies: ['trend_following', 'breakout']; } ``` ### Nova (Agresivo) ```typescript interface NovaStrategy { name: 'nova'; // Trading parameters maxPositionSize: 0.15; // 15% del balance por posición maxOpenPositions: 8; stopLossPercent: 2.0; takeProfitPercent: 5.0; // Entry conditions entrySignalMinConfidence: 0.55; // Asset allocation allowedAssets: 'top_50_market_cap'; // Dinámico includeNewListings: true; // Risk management maxDailyDrawdown: 5.0; maxTotalDrawdown: 20.0; // Strategy types strategies: ['momentum', 'altcoin_rotation']; } ``` --- ## Funcionalidades Requeridas ### RF-INV-005.1: Recepción de Señales El agente debe: - Suscribirse a señales del ML Engine via Redis Pub/Sub - Filtrar señales según estrategia del agente - Validar confianza mínima de la señal - Determinar si ejecutar o ignorar ### RF-INV-005.2: Gestión de Posiciones Para cada cuenta activa: - Calcular tamaño de posición según balance - Verificar límites de posiciones abiertas - Aplicar stop loss y take profit - Monitorear P&L en tiempo real - Cerrar posiciones cuando se alcance objetivo ### RF-INV-005.3: Ejecución de Órdenes El sistema debe: - Crear órdenes de mercado o límite - Enviar a exchange via API - Confirmar ejecución - Registrar trade en base de datos - Actualizar balance de cuenta ### RF-INV-005.4: Risk Management Reglas automáticas de protección: | Evento | Acción | |--------|--------| | Drawdown diario excedido | Pausar trading por 24h | | Drawdown total excedido | Pausar trading + notificar | | Error de exchange | Reintentar 3 veces, luego pausar | | Posición en pérdida > SL | Cerrar inmediatamente | ### RF-INV-005.5: Distribución de Ganancias Al cierre de posición con ganancia: - 80% reinvertido en la cuenta - 20% transferido a wallet del usuario (mensualmente) - Registro de distribución --- ## Modelo de Datos ### Entidad: AgentTrade ```typescript interface AgentTrade { id: string; accountId: string; agentType: 'atlas' | 'orion' | 'nova'; // Trade details symbol: string; side: 'buy' | 'sell'; type: 'market' | 'limit'; // Quantities quantity: number; price: number; value: number; // quantity * price // Status status: 'pending' | 'filled' | 'partial' | 'cancelled' | 'failed'; // P&L (for closing trades) entryPrice?: number; exitPrice?: number; pnl?: number; pnlPercent?: number; // Risk levels stopLoss: number; takeProfit: number; // Signal reference signalId?: string; signalConfidence?: number; // Exchange response exchangeOrderId?: string; executedAt?: Date; // Timestamps createdAt: Date; filledAt?: Date; } ``` ### Entidad: AgentPosition ```typescript interface AgentPosition { id: string; accountId: string; agentType: 'atlas' | 'orion' | 'nova'; // Position details symbol: string; side: 'long' | 'short'; // Quantities quantity: number; entryPrice: number; currentPrice: number; // P&L unrealizedPnl: number; unrealizedPnlPercent: number; // Risk levels stopLoss: number; takeProfit: number; // Status status: 'open' | 'closing' | 'closed'; // Timestamps openedAt: Date; closedAt?: Date; } ``` --- ## Reglas de Negocio 1. **RN-040**: El agente solo opera cuando la cuenta está en estado "active" 2. **RN-041**: El tamaño de posición nunca excede el máximo definido 3. **RN-042**: Las posiciones se cierran automáticamente al alcanzar SL/TP 4. **RN-043**: El drawdown se calcula sobre el high water mark 5. **RN-044**: Pausas por drawdown se levantan automáticamente después de 24h 6. **RN-045**: Las ganancias se distribuyen el primer día de cada mes 7. **RN-046**: Los agentes operan 24/7 mientras el mercado esté abierto --- ## Criterios de Aceptación ```gherkin Escenario: Agente ejecuta señal de compra DADO que hay una señal de compra para BTCUSDT con confianza 80% Y el agente Atlas tiene cuentas activas CUANDO el agente procesa la señal ENTONCES crea órdenes de compra para cada cuenta activa Y el tamaño es máximo 5% del balance de cada cuenta Y establece stop loss a 0.5% Y establece take profit a 1% Escenario: Agente respeta límite de posiciones DADO que una cuenta Atlas ya tiene 3 posiciones abiertas CUANDO llega una nueva señal de compra ENTONCES el agente no abre nueva posición Y registra que se ignoró por límite de posiciones Escenario: Stop loss se activa DADO que una posición tiene pérdida de 0.5% Y el agente es Atlas (SL = 0.5%) CUANDO el precio actual alcanza el nivel de stop loss ENTONCES el agente cierra la posición inmediatamente Y registra la pérdida Y actualiza el balance de la cuenta Escenario: Drawdown excede límite DADO que el drawdown diario de una cuenta alcanza 1% Y el agente es Atlas (max daily drawdown = 1%) CUANDO el sistema detecta el drawdown ENTONCES pausa el trading para esa cuenta Y notifica al usuario por email Y reanuda automáticamente en 24 horas ``` --- ## Métricas y Monitoreo ### Métricas por Agente | Métrica | Descripción | |---------|-------------| | Total Trades | Número total de trades ejecutados | | Win Rate | % de trades ganadores | | Avg Win | Ganancia promedio por trade ganador | | Avg Loss | Pérdida promedio por trade perdedor | | Profit Factor | Ganancias brutas / Pérdidas brutas | | Sharpe Ratio | Rendimiento ajustado por riesgo | | Max Drawdown | Mayor pérdida desde máximo | | Recovery Time | Tiempo promedio de recuperación | ### Alertas | Condición | Severidad | Acción | |-----------|-----------|--------| | Error de conexión a exchange | Alta | Retry + notificar | | Drawdown > 80% del límite | Media | Notificar usuario | | Drawdown excede límite | Alta | Pausar + notificar | | Win rate < 50% (30 días) | Baja | Revisar estrategia | --- ## Referencias - [ET-INV-004: Agent Architecture](../especificaciones/ET-INV-004-agents.md) - [RF-ML-002: Generación de Señales](../../OQI-006-ml-signals/requerimientos/RF-ML-002-senales.md) - [US-INV-005: Ver rendimiento](../historias-usuario/US-INV-005-ver-rendimiento.md) --- **Autor:** Requirements-Analyst **Fecha:** 2025-12-05