rckrdmrd ef42f5353a Initial commit - trading-platform

2026-01-04 06:12:13 -06:00

12 KiB

Raw Blame History

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)

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)

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)

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

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

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

RN-040: El agente solo opera cuando la cuenta está en estado "active"
RN-041: El tamaño de posición nunca excede el máximo definido
RN-042: Las posiciones se cierran automáticamente al alcanzar SL/TP
RN-043: El drawdown se calcula sobre el high water mark
RN-044: Pausas por drawdown se levantan automáticamente después de 24h
RN-045: Las ganancias se distribuyen el primer día de cada mes
RN-046: Los agentes operan 24/7 mientras el mercado esté abierto

Criterios de Aceptación

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

Autor: Requirements-Analyst Fecha: 2025-12-05

12 KiB Raw Blame History