# 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
