| id |
title |
type |
project |
version |
updated_date |
| README |
Trading y Charts |
Documentation |
trading-platform |
1.0.0 |
2026-01-04 |
OQI-003: Trading y Charts
Resumen Ejecutivo
La épica OQI-003 implementa la plataforma de trading con charts profesionales, indicadores técnicos, watchlists personalizables y sistema de paper trading para simulación sin riesgo.
Metadata
| Campo |
Valor |
| ID |
OQI-003 |
| Nombre |
Trading y Charts |
| Módulo |
trading |
| Fase |
Fase 1 - MVP |
| Prioridad |
P1 |
| Estado |
Pendiente |
| Story Points |
55 SP |
| Sprint(s) |
Sprint 3-4 |
Objetivo
Proporcionar una plataforma de trading completa que permita a los usuarios:
- Visualizar charts profesionales con múltiples timeframes
- Aplicar indicadores técnicos para análisis
- Crear y gestionar watchlists personalizadas
- Practicar trading con paper trading (simulación)
- Revisar historial de operaciones y métricas de rendimiento
Alcance
Incluido
| Feature |
Descripción |
| Charts |
Gráficos de velas con Lightweight Charts (TradingView clone) |
| Timeframes |
1m, 5m, 15m, 1h, 4h, 1D, 1W |
| Indicadores Técnicos |
SMA, EMA, RSI, MACD, Bollinger Bands |
| ML Overlay |
Indicadores predictivos del modelo ML superpuestos en chart |
| Señales ML |
Visualización de señales de entrada/salida del modelo |
| AMD Zones |
Zonas de Acumulación/Manipulación/Distribución |
| Watchlists |
Listas personalizables de activos |
| Paper Trading |
Simulación de operaciones sin dinero real |
| Historial |
Registro completo de operaciones |
| Métricas |
Win rate, P&L, Sharpe ratio básico |
| Alertas ML |
Notificaciones cuando el modelo genera señales |
ML Overlay Features
| Indicador ML |
Visualización |
Fuente |
| RangePredictor |
Bandas de predicción (ΔHigh/ΔLow) |
TradingAgent |
| TPSLClassifier |
Colores TP (verde) / SL (rojo) |
TradingAgent |
| AMDDetector |
Zonas coloreadas (Acc/Manip/Dist) |
TradingAgent |
| SignalGenerator |
Flechas de entrada (▲ compra, ▼ venta) |
TradingAgent |
| Confidence |
Opacidad según confianza del modelo |
TradingAgent |
Excluido
| Feature |
Razón |
Fase |
| Trading real |
Requiere broker integration |
Vía Agentes |
| Order book |
Complejidad |
Backlog |
| Depth charts |
Nicho avanzado |
Backlog |
| Screener avanzado |
Post-MVP |
Fase 2 |
Arquitectura
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Trading │ │ Watchlist │ │ Paper │ │
│ │ Charts │ │ Manager │ │ Trading │ │
│ │ + ML Overlay│ │ │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼─────────────────────┘
│ │ │
└────────────────┼────────────────┘
│ HTTPS / WebSocket
▼
┌─────────────────────────────────────────────────────────────────┐
│ BACKEND API │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TRADING CONTROLLER │ │
│ │ GET /trading/candles GET /trading/indicators │ │
│ │ POST /trading/orders GET /trading/watchlists │ │
│ │ GET /trading/positions GET /trading/history │ │
│ │ GET /trading/ml/overlay GET /trading/ml/signals │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Market │ │ Order │ │ Position │ │ Watchlist │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ML OVERLAY SERVICE │ │
│ │ - Fetch predictions from ML Engine │ │
│ │ - Transform to chart overlay format │ │
│ │ - Cache signals for performance │ │
│ └─────────────────────────────────────────────────────────┘ │
└────────┼──────────────┼──────────────┼──────────────┼───────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────────────────────┐ ┌─────────────────┐
│ Binance │ │ ML ENGINE │ │ PostgreSQL │
│ API │ │ (TradingAgent) │ │ trading schema │
│ │ │ - RangePredictor │ │ │
│ - Candles │ │ - TPSLClassifier │ │ - orders │
│ - Prices │ │ - AMDDetector │ │ - positions │
│ - Stream │ │ - SignalGenerator │ │ - watchlists │
└─────────────┘ └─────────────────────────┘ └─────────────────┘
Flujo de ML Overlay
Usuario solicita chart XAUUSD 1H
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. Frontend: GET /trading/candles/XAUUSD?interval=1h │
│ 2. Frontend: GET /trading/ml/overlay/XAUUSD?interval=1h │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Backend: ML Overlay Service │
│ │
│ 1. Check Redis cache for recent predictions │
│ 2. If miss: Call ML Engine API │
│ - POST /predict {symbol, interval, candles} │
│ 3. Transform response to overlay format │
│ 4. Cache for 5 minutes │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Response: ML Overlay Data │
│ { │
│ "rangePrediction": { "high": [...], "low": [...] }, │
│ "tpslClassification": [{ "index": 50, "type": "tp" }], │
│ "amdZones": [{ "start": 10, "end": 25, "phase": "acc" }], │
│ "signals": [{ "index": 50, "type": "buy", "conf": 0.85 }] │
│ } │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Frontend: Render Chart with Overlay │
│ │
│ - Draw candles (standard) │
│ - Draw range bands (prediction envelope) │
│ - Color background zones (AMD phases) │
│ - Draw signal markers (arrows with confidence opacity) │
└─────────────────────────────────────────────────────────────────┘
Flujos Principales
1. Visualización de Chart
Usuario Frontend Backend Binance
│ │ │ │
│─── Selecciona BTCUSDT ──▶│ │ │
│ │─── GET /trading/candles ─▶│ │
│ │ │─── GET klines ────────▶│
│ │ │◀── OHLCV data ─────────│
│ │◀── Candles + indicators ─│ │
│◀── Render chart ─────────│ │ │
│ │ │ │
│ │─── WS connect ───────────▶│ │
│◀── Real-time updates ────│◀── Stream updates ───────│◀── WebSocket ─────────│
2. Paper Trading Order
Usuario Frontend Backend DB
│ │ │ │
│─── Click BUY BTCUSDT ───▶│ │ │
│ │─── POST /trading/orders ─▶│ │
│ │ │─── Validate balance ──▶│
│ │ │◀── OK ─────────────────│
│ │ │─── Get current price ──│
│ │ │─── INSERT order ───────▶│
│ │ │─── UPDATE positions ───▶│
│ │◀── Order executed ───────│ │
│◀── Success notification ─│ │ │
3. Gestión de Watchlist
Usuario Frontend Backend DB
│ │ │ │
│─── Add to watchlist ────▶│ │ │
│ │─── POST /watchlists/:id/symbols ─▶│ │
│ │ │─── INSERT symbol ─────▶│
│ │◀── Updated watchlist ────│ │
│◀── Symbol added ─────────│ │ │
Modelo de Datos
Tablas Principales
-- Watchlists del usuario
CREATE TABLE trading.watchlists (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES public.users(id),
name VARCHAR(100) NOT NULL,
description TEXT,
is_default BOOLEAN DEFAULT FALSE,
sort_order INTEGER DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- Símbolos en watchlists
CREATE TABLE trading.watchlist_symbols (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
watchlist_id UUID REFERENCES trading.watchlists(id) ON DELETE CASCADE,
symbol VARCHAR(20) NOT NULL,
notes TEXT,
alert_price_above DECIMAL(20,8),
alert_price_below DECIMAL(20,8),
sort_order INTEGER DEFAULT 0,
added_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(watchlist_id, symbol)
);
-- Órdenes de paper trading
CREATE TABLE trading.paper_orders (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES public.users(id),
symbol VARCHAR(20) NOT NULL,
side order_side_enum NOT NULL, -- buy | sell
type order_type_enum NOT NULL, -- market | limit | stop_limit
status order_status_enum DEFAULT 'pending',
quantity DECIMAL(20,8) NOT NULL,
price DECIMAL(20,8), -- null for market orders
stop_price DECIMAL(20,8),
filled_quantity DECIMAL(20,8) DEFAULT 0,
filled_price DECIMAL(20,8),
take_profit DECIMAL(20,8),
stop_loss DECIMAL(20,8),
created_at TIMESTAMPTZ DEFAULT NOW(),
filled_at TIMESTAMPTZ,
cancelled_at TIMESTAMPTZ
);
-- Posiciones abiertas
CREATE TABLE trading.paper_positions (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES public.users(id),
symbol VARCHAR(20) NOT NULL,
side position_side_enum NOT NULL, -- long | short
quantity DECIMAL(20,8) NOT NULL,
entry_price DECIMAL(20,8) NOT NULL,
current_price DECIMAL(20,8),
unrealized_pnl DECIMAL(20,8) DEFAULT 0,
realized_pnl DECIMAL(20,8) DEFAULT 0,
take_profit DECIMAL(20,8),
stop_loss DECIMAL(20,8),
opened_at TIMESTAMPTZ DEFAULT NOW(),
closed_at TIMESTAMPTZ,
UNIQUE(user_id, symbol) -- Una posición por símbolo
);
-- Balance virtual de paper trading
CREATE TABLE trading.paper_balances (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES public.users(id) UNIQUE,
balance DECIMAL(20,8) DEFAULT 10000.00, -- $10,000 inicial
equity DECIMAL(20,8) DEFAULT 10000.00,
margin_used DECIMAL(20,8) DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- Historial de trades cerrados
CREATE TABLE trading.paper_trades (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES public.users(id),
symbol VARCHAR(20) NOT NULL,
side position_side_enum NOT NULL,
entry_price DECIMAL(20,8) NOT NULL,
exit_price DECIMAL(20,8) NOT NULL,
quantity DECIMAL(20,8) NOT NULL,
pnl DECIMAL(20,8) NOT NULL,
pnl_percent DECIMAL(10,4) NOT NULL,
duration_minutes INTEGER,
opened_at TIMESTAMPTZ NOT NULL,
closed_at TIMESTAMPTZ NOT NULL
);
API Endpoints
Market Data
| Method |
Endpoint |
Descripción |
| GET |
/trading/symbols |
Lista de símbolos disponibles |
| GET |
/trading/candles/:symbol |
Velas OHLCV |
| GET |
/trading/ticker/:symbol |
Precio actual |
| GET |
/trading/indicators/:symbol |
Indicadores técnicos |
| WS |
/trading/stream/:symbol |
Stream de precios |
Watchlists
| Method |
Endpoint |
Descripción |
| GET |
/trading/watchlists |
Listar watchlists |
| POST |
/trading/watchlists |
Crear watchlist |
| PATCH |
/trading/watchlists/:id |
Actualizar watchlist |
| DELETE |
/trading/watchlists/:id |
Eliminar watchlist |
| POST |
/trading/watchlists/:id/symbols |
Agregar símbolo |
| DELETE |
/trading/watchlists/:id/symbols/:symbol |
Quitar símbolo |
Paper Trading
| Method |
Endpoint |
Descripción |
| GET |
/trading/paper/balance |
Balance virtual |
| POST |
/trading/paper/balance/reset |
Reiniciar a $10,000 |
| GET |
/trading/paper/positions |
Posiciones abiertas |
| POST |
/trading/paper/orders |
Crear orden |
| DELETE |
/trading/paper/orders/:id |
Cancelar orden |
| GET |
/trading/paper/orders |
Historial de órdenes |
| GET |
/trading/paper/trades |
Historial de trades |
| GET |
/trading/paper/stats |
Estadísticas de rendimiento |
ML Overlay (Integración con TradingAgent)
| Method |
Endpoint |
Descripción |
| GET |
/trading/ml/overlay/:symbol |
Overlay completo para chart |
| GET |
/trading/ml/signals/:symbol |
Señales de entrada/salida |
| GET |
/trading/ml/prediction/:symbol |
Predicción de rango |
| GET |
/trading/ml/amd/:symbol |
Zonas AMD detectadas |
| GET |
/trading/ml/confidence/:symbol |
Confianza del modelo |
| WS |
/trading/ml/stream/:symbol |
Stream de predicciones |
Ejemplo Response ML Overlay
{
"symbol": "XAUUSD",
"interval": "1h",
"timestamp": "2025-12-05T12:00:00Z",
"overlay": {
"rangePrediction": {
"deltaHigh": [0.15, 0.18, 0.22, ...],
"deltaLow": [-0.12, -0.10, -0.14, ...]
},
"signals": [
{
"index": 95,
"type": "buy",
"confidence": 0.85,
"entry": 2045.50,
"tp": 2065.00,
"sl": 2035.00
}
],
"amdZones": [
{ "start": 50, "end": 65, "phase": "accumulation" },
{ "start": 66, "end": 78, "phase": "manipulation" },
{ "start": 79, "end": 95, "phase": "distribution" }
],
"tpslProbability": {
"tp": 0.72,
"sl": 0.28
},
"modelConfidence": 0.85
}
}
Indicadores Técnicos
Indicadores Tradicionales
| Indicador |
Parámetros |
Descripción |
| SMA |
period: 5, 10, 20, 50, 200 |
Simple Moving Average |
| EMA |
period: 5, 10, 20, 50, 200 |
Exponential Moving Average |
| RSI |
period: 14 |
Relative Strength Index (0-100) |
| MACD |
fast: 12, slow: 26, signal: 9 |
Moving Average Convergence Divergence |
| BB |
period: 20, stdDev: 2 |
Bollinger Bands |
| ATR |
period: 14 |
Average True Range |
| Volume |
- |
Barras de volumen |
Indicadores ML (TradingAgent)
| Indicador |
Visualización |
Descripción |
| ML Range |
Bandas semi-transparentes |
Predicción de rango ΔHigh/ΔLow |
| ML Signal |
Flechas ▲/▼ con opacidad |
Señales de entrada del modelo |
| AMD Zone |
Background coloreado |
Fases de mercado detectadas |
| TP/SL Prob |
Indicador lateral |
Probabilidad de TP vs SL |
| Confidence |
Barra inferior |
Confianza del modelo 0-100% |
Colores AMD
| Fase |
Color |
Descripción |
| Accumulation |
Verde suave (#4CAF5020) |
Acumulación institucional |
| Manipulation |
Amarillo (#FFC10720) |
Manipulación de mercado |
| Distribution |
Rojo suave (#F4433620) |
Distribución de posiciones |
Timeframes Soportados
| Timeframe |
Label |
Candles por defecto |
| 1m |
1 minuto |
500 |
| 5m |
5 minutos |
300 |
| 15m |
15 minutos |
200 |
| 1h |
1 hora |
168 |
| 4h |
4 horas |
100 |
| 1D |
1 día |
100 |
| 1W |
1 semana |
52 |
Métricas de Paper Trading
{
"stats": {
"totalTrades": 45,
"winningTrades": 28,
"losingTrades": 17,
"winRate": 62.22,
"totalPnl": 2450.50,
"totalPnlPercent": 24.51,
"avgWin": 150.25,
"avgLoss": -85.30,
"profitFactor": 2.45,
"maxDrawdown": -8.5,
"sharpeRatio": 1.85,
"avgTradeDuration": "4h 23m"
}
}
Seguridad
Rate Limiting
| Endpoint |
Límite |
Ventana |
/trading/candles |
30 |
1 min |
/trading/stream |
5 conexiones |
- |
/trading/paper/orders |
20 |
1 min |
| General API |
100 |
1 min |
Validaciones
- Balance suficiente para órdenes
- Símbolos válidos de la lista soportada
- Límites de posición por símbolo
- Cantidad mínima por orden
Entregables
| Entregable |
Ruta |
Estado |
| Schema DB |
apps/database/schemas/03_trading_schema.sql |
✅ |
| Market Service |
apps/backend/src/modules/trading/services/market.service.ts |
Pendiente |
| Order Service |
apps/backend/src/modules/trading/services/order.service.ts |
Pendiente |
| Watchlist Service |
apps/backend/src/modules/trading/services/watchlist.service.ts |
Pendiente |
| Trading Controller |
apps/backend/src/modules/trading/controllers/trading.controller.ts |
Pendiente |
| Trading Page |
apps/frontend/src/modules/trading/pages/Trading.tsx |
Pendiente |
| Chart Component |
apps/frontend/src/modules/trading/components/TradingChart.tsx |
Pendiente |
| Order Panel |
apps/frontend/src/modules/trading/components/OrderPanel.tsx |
Pendiente |
| Watchlist Panel |
apps/frontend/src/modules/trading/components/WatchlistPanel.tsx |
Pendiente |
Dependencias
Esta épica depende de:
| Épica/Módulo |
Estado |
Bloqueante |
Razón |
| OQI-001 Auth |
✅ Completado |
Sí |
Autenticación de usuarios |
| OQI-006 ML Signals |
Pendiente |
Parcial |
ML overlay requiere predicciones |
Esta épica bloquea:
| Épica/Módulo |
Razón |
| OQI-007 LLM Agent |
El copiloto usa los charts para análisis |
| OQI-008 Portfolio Manager |
Dashboard muestra charts de rendimiento |
Integración con TradingAgent
Esta épica integra el motor ML existente ubicado en:
[LEGACY: apps/ml-engine - migrado desde TradingAgent]/
Ver documento de integración:
docs/01-arquitectura/INTEGRACION-TRADINGAGENT.md
Riesgos
| Riesgo |
Probabilidad |
Impacto |
Mitigación |
| Rate limits Binance |
Alta |
Medio |
Caché de datos, WebSocket |
| Latencia en charts |
Media |
Alto |
CDN para assets, lazy loading |
| Cálculo de indicadores lento |
Baja |
Medio |
Web Workers, caché |
Referencias
rckrdmrd
a7cca885f0