workspace/projects/trading-platform/apps/trading-agents/PAPER_TRADING_GUIDE.md

Paper Trading Guide

Guía completa para paper trading con Binance Testnet

1. Configuración de Binance Testnet

Paso 1: Crear cuenta en Testnet

1. Ir a https://testnet.binancefuture.com/
2. Hacer clic en "Register" (esquina superior derecha)
3. Crear cuenta con email (no requiere verificación real)
4. Iniciar sesión

Paso 2: Obtener API Keys

1. Una vez logueado, ir a "API Management"
2. Hacer clic en "Generate HMAC_SHA256 Key"
3. Ingresar un nombre (ejemplo: "OrbiQuant Trading Bot")
4. Copiar el API Key y Secret Key
5. IMPORTANTE: Guardar el Secret Key - solo se muestra una vez

Paso 3: Configurar permisos

1. En la configuración de la API key, habilitar:
   • ✓ Enable Reading
   • ✓ Enable Spot & Margin Trading
   • ✓ Enable Futures

2. Configuración Local

Crear archivo .env

cd apps/trading-agents
cp .env.example .env

Editar .env con tus API keys:

BINANCE_API_KEY=tu_api_key_aqui
BINANCE_API_SECRET=tu_secret_key_aqui
BINANCE_TESTNET=true

ML_ENGINE_URL=http://localhost:8000
ML_ENGINE_API_KEY=dev_ml_key

API_PORT=8003
API_HOST=0.0.0.0

3. Iniciar el Servicio

Opción A: Local (Python)

# Activar entorno virtual
source venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt

# Iniciar servicio
python -m src.api.main

Opción B: Docker

# Construir imagen
docker-compose build

# Iniciar servicio
docker-compose up -d

# Ver logs
docker-compose logs -f trading-agents

4. Testing Básico

Verificar conexión a Binance Testnet

import asyncio
from src.exchange.binance_client import BinanceClient

async def test_connection():
    async with BinanceClient(
        api_key="tu_api_key",
        api_secret="tu_secret_key",
        testnet=True
    ) as client:
        # Test 1: Health check
        healthy = await client.health_check()
        print(f"Binance Testnet: {'✓ Connected' if healthy else '✗ Failed'}")

        # Test 2: Get account info
        account = await client.get_account_info()
        print(f"Account Balance: {account}")

        # Test 3: Get ticker price
        btc_price = await client.get_ticker_price("BTCUSDT")
        print(f"BTC Price: ${btc_price:.2f}")

asyncio.run(test_connection())

5. Ejecutar Agente con Paper Trading

Atlas Agent (Conservador)

import asyncio
from src.agents.atlas import AtlasAgent
from src.exchange.binance_client import BinanceClient

async def run_atlas_paper_trading():
    # 1. Crear cliente de Binance
    client = BinanceClient(
        api_key="tu_api_key",
        api_secret="tu_secret_key",
        testnet=True
    )

    # 2. Verificar balance inicial
    async with client:
        balance = await client.get_balance()
        usdt_balance = next(
            (b for b in balance if b['asset'] == 'USDT'),
            None
        )
        initial_equity = float(usdt_balance['availableBalance'])
        print(f"Initial USDT Balance: ${initial_equity:.2f}")

        # 3. Crear y iniciar agente
        agent = AtlasAgent(equity=initial_equity)
        await agent.start()

        print(f"\nAtlas Agent started")
        print(f"Max Drawdown: {agent.config.max_drawdown}%")
        print(f"Position Size: {agent.config.position_size_pct}%")
        print(f"Allowed Pairs: {agent.config.allowed_pairs}")

        # 4. Simular señal de trading
        btc_price = await client.get_ticker_price("BTCUSDT")
        signal = {
            'symbol': 'BTCUSDT',
            'action': 'buy',
            'confidence': 0.85,
            'price': btc_price
        }

        print(f"\nProcessing signal: BUY BTCUSDT @ ${btc_price:.2f}")
        await agent.on_signal(signal)

        # 5. Si el agente abrió posición, ejecutar en Binance Testnet
        if agent.positions:
            pos = agent.positions[0]
            print(f"\nPlacing order on Binance Testnet...")

            order = await client.place_market_order(
                symbol=pos.symbol,
                side='BUY',
                quantity=pos.quantity
            )

            print(f"Order placed: {order}")

        # 6. Mostrar métricas
        metrics = agent.get_metrics()
        print(f"\nAgent Metrics:")
        for key, value in metrics.items():
            print(f"  {key}: {value}")

        await agent.stop()

asyncio.run(run_atlas_paper_trading())

6. Monitoreo en Tiempo Real

Usando la API

# 1. Iniciar agente
curl -X POST http://localhost:8003/agents/atlas/start \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "atlas", "initial_equity": 1000.0}'

# 2. Ver estado
curl http://localhost:8003/agents/atlas/status

# 3. Ver posiciones
curl http://localhost:8003/agents/atlas/positions

# 4. Ver métricas
curl http://localhost:8003/agents/atlas/metrics

7. Testing de Estrategias

Mean Reversion

import asyncio
import pandas as pd
from src.strategies.mean_reversion import MeanReversionStrategy
from src.exchange.binance_client import BinanceClient

async def test_mean_reversion():
    # Obtener datos históricos
    async with BinanceClient(
        api_key="tu_key",
        api_secret="tu_secret",
        testnet=True
    ) as client:
        # Get klines (candlestick data)
        klines = await client.get_klines("BTCUSDT", "1h", 100)

        # Convert to DataFrame
        df = pd.DataFrame(klines, columns=[
            'timestamp', 'open', 'high', 'low', 'close',
            'volume', 'close_time', 'quote_volume', 'trades',
            'taker_buy_base', 'taker_buy_quote', 'ignore'
        ])

        df['close'] = df['close'].astype(float)
        df['high'] = df['high'].astype(float)
        df['low'] = df['low'].astype(float)

        # Test strategy
        strategy = MeanReversionStrategy({
            'sma_period': 20,
            'std_multiplier': 2.0,
            'rsi_period': 14
        })

        signal = strategy.generate_signal(df)

        if signal:
            print(f"Signal: {signal.signal_type.value}")
            print(f"Confidence: {signal.confidence:.2f}")
            print(f"Reason: {signal.reason}")
        else:
            print("No signal generated")

asyncio.run(test_mean_reversion())

8. Mejores Prácticas

1. Empezar con montos pequeños

# Usar $100-$1000 para testing
agent = AtlasAgent(equity=100.0)

2. Monitorear métricas constantemente

# Verificar después de cada trade
metrics = agent.get_metrics()
print(f"Win Rate: {metrics['win_rate']:.2f}%")
print(f"Drawdown: {metrics['current_drawdown']:.2f}%")

3. Probar cada estrategia individualmente

# Test solo Mean Reversion
agent.config.strategies = ['mean_reversion']

4. Usar stop loss y take profit

# Siempre definir límites
position = Position(
    symbol="BTCUSDT",
    side="buy",
    quantity=0.01,
    entry_price=45000.0,
    stop_loss=44100.0,  # -2%
    take_profit=45900.0  # +2%
)

9. Troubleshooting

Error: "Invalid API Key"

# Verificar que las keys sean de Testnet
# Las keys de producción NO funcionan en testnet
# Regenerar keys si es necesario

Error: "Insufficient Balance"

# Verificar balance en Binance Testnet
# El testnet da $100,000 USDT virtuales al registrarse
# Si se agotó, crear nueva cuenta de testnet

Error: "Symbol not found"

# Verificar que el símbolo sea correcto
# Formato: "BTCUSDT" (sin espacios ni guiones)
# Lista de símbolos: client.get_exchange_info()

10. Recursos Adicionales

• Binance Testnet
• Binance API Docs
• Trading Agents README

Notas Importantes

1. NO usar API keys de producción en testnet
2. Testnet usa datos de mercado reales pero dinero virtual
3. Las órdenes en testnet NO afectan tu dinero real
4. Probar exhaustivamente antes de pasar a producción
5. Siempre usar límites de riesgo conservadores