rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
382 lines
12 KiB
Markdown
382 lines
12 KiB
Markdown
---
|
|
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
|