# 🤖 Trading Bot - Proyecto Completo

Bot de trading algorítmico desarrollado desde cero con Python, PostgreSQL y Machine Learning.

## 📋 Tabla de Contenidos

- [Estado del Proyecto](#-estado-del-proyecto)
- [Requisitos](#-requisitos)
- [Instalación](#-instalación)
- [Configuración](#-configuración)
- [Uso](#-uso)
- [Estructura del Proyecto](#-estructura-del-proyecto)
- [Base de Datos](#-base-de-datos)
- [Scripts Disponibles](#-scripts-disponibles)
- [Testing](#-testing)
- [Roadmap](#-roadmap)
- [Troubleshooting](#-troubleshooting)

## 🎯 Estado del Proyecto

### ✅ Completado (Semanas 1-2 y 3-4)

**Semanas 1-2: Infraestructura de Datos**
- ✅ Sistema de logging robusto con rotación de archivos
- ✅ Conexión a exchanges vía CCXT (Binance por defecto)
- ✅ Descarga de datos históricos con reintentos automáticos
- ✅ Descarga incremental (continuar desde último timestamp)
- ✅ Procesamiento y limpieza de datos
- ✅ Detección de gaps y outliers
- ✅ Resampleo de timeframes (1h → 4h, 1d, etc.)
- ✅ Cálculo de retornos (simples y logarítmicos)
- ✅ Almacenamiento en PostgreSQL con índices optimizados
- ✅ Sistema anti-duplicados con constraints únicos
- ✅ Caché con Redis (opcional)
- ✅ Script de descarga masiva para múltiples símbolos
- ✅ Tests unitarios
- ✅ Manejo de errores y reintentos

**Semanas 3-4: Backtesting Engine**
- ✅ Motor de backtesting completo
- ✅ Clase base abstracta para estrategias
- ✅ Sistema de trades y posiciones
- ✅ 3 estrategias implementadas:
  - Moving Average Crossover (SMA/EMA)
  - RSI Strategy
  - Buy & Hold (baseline)
- ✅ Métricas de performance:
  - Sharpe Ratio, Sortino Ratio
  - Max Drawdown, Calmar Ratio
  - Win Rate, Profit Factor
  - Expectancy, Risk/Reward
- ✅ Script de comparación de estrategias
- ✅ Simulación de comisiones y slippage
- ✅ Gestión de capital y position sizing

### 🔬 Research y Optimización (ACTUAL)

**Estado actual: research cuantitativo serio (in-sample).**

#### 📊 Datos históricos actuales
- 5 criptomonedas (BTC, ETH, BNB, SOL, XRP)
- 3 timeframes (1h, 4h, 1d)
- ≈ 3 años de histórico
- ~26.000 velas por símbolo en 1h
- Datos limpios, validados y persistidos

#### 📈 Indicadores calculados y almacenados
- returns
- log_returns
- **ADX (Average Directional Index)**  
  → calculado una sola vez en el pipeline de datos y guardado en PostgreSQL

#### 🔧 Optimización de parámetros
- Grid search exhaustivo sobre:
  - fast_period
  - slow_period
  - tipo de media (SMA / EMA)
  - uso de ADX
  - umbral de ADX
- Métrica principal de selección: **Sharpe Ratio**
- Optimización **in-sample** (aún sin walk-forward)

**Mejor configuración encontrada (BTC/USDT 1h):**

- Fast MA: 15
- Slow MA: 50
- MA Type: SMA
- ADX activo
- ADX threshold: 30
- Sharpe ≈ 0.24
- Return ≈ +188%
- Max Drawdown ≈ -24%
- Total trades: 17

#### 📊 Visualización de resultados
- Equity curve
- Drawdown
- Distribución de retornos por trade
- Trades sobre el precio
- Dashboard consolidado

Conclusión preliminar:
> Menos trades + filtro de tendencia = mayor robustez.

### 🔄 En Progreso

- ⏳ Walk-forward validation (en desarrollo)
- ⏳ Position sizing dinámico (en desarrollo)
- ⏳ Stops dinámicos (en desarrollo)
- ⏳ Portfolio multi-activo (en desarrollo)
- ⏳ Machine Learning (Semanas 5-8 planificadas)

### 📅 Planificado

- 📋 Machine Learning (Semanas 5-8 planificadas)
- 📋 Live trading con paper trading
- 📋 Gestión de riesgo avanzada
- 📋 Optimización de estrategias
- 📋 Dashboard web
- 📋 Alertas y notificaciones

## 🔧 Requisitos

### Software
- **Python 3.10+** (probado con 3.12.3)
- **PostgreSQL 13+** 
- **Redis 6+** (opcional, para caché)
- Git

### Hardware Recomendado
- 8GB RAM (mínimo)
- 20GB espacio en disco
- Para ML: GPU recomendada (futuro)

## 📦 Instalación

### 1. Clonar el repositorio

```bash
git clone <tu-repositorio>
cd trading-bot
```

### 2. Crear entorno virtual

```bash
python3 -m venv venv

# Linux/Mac:
source venv/bin/activate

# Windows:
venv\Scripts\activate
```

### 3. Instalar dependencias

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

### 4. Instalar PostgreSQL

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

**macOS (con Homebrew):**
```bash
brew install postgresql@16
brew services start postgresql@16
```

**Windows:**
Descargar instalador desde [postgresql.org](https://www.postgresql.org/download/windows/)

### 5. Configurar base de datos

```bash
# Conectar a PostgreSQL
sudo -u postgres psql

# Crear base de datos y usuario
CREATE DATABASE trading_bot;
CREATE USER trading_user WITH PASSWORD 'tu_password_seguro';
GRANT ALL PRIVILEGES ON DATABASE trading_bot TO trading_user;

# Conectar a la base de datos
\c trading_bot

# Dar permisos sobre el schema
GRANT ALL ON SCHEMA public TO trading_user;

# Salir
\q
```

### 6. Gestión del servicio PostgreSQL

**Iniciar PostgreSQL:**
```bash
sudo systemctl start postgresql
```

**Verificar estado:**
```bash
sudo systemctl status postgresql
```

**Detener PostgreSQL:**
```bash
sudo systemctl stop postgresql
```

**Reiniciar PostgreSQL:**
```bash
sudo systemctl restart postgresql
```

**Habilitar inicio automático al arrancar el sistema:**
```bash
sudo systemctl enable postgresql
```

**Deshabilitar inicio automático:**
```bash
sudo systemctl disable postgresql
```

**Ver si está habilitado el inicio automático:**
```bash
systemctl is-enabled postgresql
```

### 6. Instalar Redis (opcional pero recomendado)

**Ubuntu/Debian:**
```bash
sudo apt install redis-server
sudo systemctl start redis
```

**macOS:**
```bash
brew install redis
brew services start redis
```

## ⚙️ Configuración

### 1. Crear archivo de configuración

```bash
# El archivo debe estar en config/secrets.env
# Usa este template:
```

```env
# Exchange (para datos públicos NO necesitas API keys)
EXCHANGE_NAME=binance
API_KEY=
API_SECRET=

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=trading_bot
DB_USER=trading_user
DB_PASSWORD=tu_password_aqui

# Redis (opcional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# General
ENVIRONMENT=development
LOG_LEVEL=INFO
```

### 2. Configurar símbolos y timeframes

Edita `config/settings.yaml` para personalizar:

```yaml
trading:
  symbols:
    - BTC/USDT
    - ETH/USDT
    - BNB/USDT
  timeframes:
    - 1h
    - 4h
    - 1d
  
data:
  fetch_interval: 60
  historical_days: 120
  max_retries: 3
```

## 🚀 Uso

### Demo rápido (verificar instalación)

```bash
python main.py
```

Este script:
- Descarga 1 día de BTC/USDT
- Muestra el pipeline completo
- Guarda en PostgreSQL
- Muestra estadísticas

### Descarga masiva de datos

```bash
python download_data.py
```

Este script descarga:
- Múltiples símbolos configurables
- Múltiples timeframes
- Días históricos configurables
- Muestra progreso en tiempo real
- Previene duplicados automáticamente

**Personalizar descarga:**
Edita `download_data.py` líneas ~28-45:

```python
symbols = [
    'BTC/USDT',
    'ETH/USDT',
    # Añade más aquí
]

timeframes = ['1h', '4h', '1d']
days_back = 120  # Cambia aquí
```

### Backtesting

**Ejecutar backtest simple:**
```bash
python backtest.py
```

Esto ejecuta un backtest con:
- Estrategia: Moving Average Crossover (10/30)
- Símbolo: BTC/USDT
- Periodo: 60 días
- Capital inicial: $10,000

**Comparar múltiples estrategias:**
```bash
python backtest.py compare
```

Compara 4 estrategias diferentes:
- Buy & Hold
- MA Cross (10/30 SMA)
- MA Cross (20/50 EMA)
- RSI (30/70)

### Uso programático

**Pipeline de datos:**
```python
from src.data.fetcher import DataFetcher
from src.data.processor import DataProcessor
from src.data.storage import StorageManager

# Inicializar
fetcher = DataFetcher('binance')
processor = DataProcessor()
storage = StorageManager(...)

# Descargar
df = fetcher.fetch_historical('BTC/USDT', timeframe='1h', days=30)

# Procesar
df_clean = processor.clean_data(df)
df_clean = processor.calculate_returns(df_clean)

# Guardar
storage.save_ohlcv(df_clean)
```

**Backtesting:**
```python
from src.data.storage import StorageManager
from src.backtest import BacktestEngine
from src.strategies import MovingAverageCrossover

# Cargar datos
storage = StorageManager(...)
data = storage.load_ohlcv('BTC/USDT', '1h')

# Crear estrategia
strategy = MovingAverageCrossover(fast_period=10, slow_period=30)

# Ejecutar backtest
engine = BacktestEngine(
    strategy=strategy,
    initial_capital=10000,
    commission=0.001,
    position_size=0.95
)

results = engine.run(data)

# Ver resultados
from src.backtest.metrics import print_backtest_report
print_backtest_report(results)
```

## 📁 Estructura del Proyecto

```
trading-bot/
├── config/                   # Configuración
│   ├── settings.yaml         # Configuración general
│   └── secrets.env           # Credenciales (NO subir a git)
│
├── src/                      # Código fuente
│   ├── backtest/             # Motor de backtesting
│   │   ├── __init__.py
│   │   ├── engine.py         # BacktestEngine
│   │   ├── metrics.py        # Métricas de performance
│   │   ├── optimizer.py      # Optimizador de parámetros
│   │   ├── strategy.py       # Clase base Strategy
│   │   ├── trade.py          # Trade, Position
│   │   └── visualizer.py     # Visualizador de estrategias
│   │
│   ├── strategies/           # Estrategias de trading
│   │   ├── __init__.py
│   │   ├── moving_average.py # MA Crossover
│   │   ├── rsi_strategy.py   # RSI Strategy
│   │   ├── buy_and_hold.py   # Buy & Hold
│   │   ├── base.py           # (futuro)
│   │   ├── ml_model.py       # (futuro)
│   │   └── signals.py        # (futuro)
│   │
│   ├── data/                # Módulo de datos
│   │   ├── __init__.py
│   │   ├── fetcher.py       # Descarga desde exchanges
│   │   ├── processor.py     # Limpieza y procesamiento
│   │   └── storage.py       # PostgreSQL + Redis
│   │
│   └── utils/               # Utilidades
│       ├── __init__.py
│       ├── logger.py        # Sistema de logging
│       └── alerts.py        # (futuro)
│
├── tests/                   # Tests unitarios
│   ├── test_data.py
│   ├── test_optimizer.py
│   └── test_visualizer.py
│
├── data/                    # Datos locales
│   ├── historical/         # Backups (futuro)
│   └── exports/            # Exportaciones (futuro)
│
├── logs/                    # Archivos de log
│   ├── trading_bot_*.log
│   └── errors_*.log
│
├── main.py                  # Demo/testing
├── download_data.py         # Descarga masiva
├── backtest.py              # Backtesting runner
├── requirements.txt         # Dependencias
├── .gitignore
├── BACKTESTING.md
└── README.md
```

## 🗄️ Base de Datos

### Ubicación de PostgreSQL

```bash
# Ver ubicación de los datos
sudo -u postgres psql -c "SHOW data_directory;"
# Típicamente: /var/lib/postgresql/16/main
```

### Gestión del servicio PostgreSQL

**Comandos básicos:**
```bash
# Iniciar PostgreSQL
sudo systemctl start postgresql

# Detener PostgreSQL
sudo systemctl stop postgresql

# Reiniciar PostgreSQL
sudo systemctl restart postgresql

# Ver estado
sudo systemctl status postgresql

# Habilitar inicio automático al arrancar el sistema
sudo systemctl enable postgresql

# Deshabilitar inicio automático
sudo systemctl disable postgresql

# Verificar si está habilitado
systemctl is-enabled postgresql
```

**Nota:** Por defecto, después de la instalación PostgreSQL está configurado para iniciar automáticamente. Si prefieres iniciarlo manualmente cada vez:
```bash
sudo systemctl disable postgresql
```

### Tabla OHLCV (estructura)

```sql
CREATE TABLE ohlcv (
    id SERIAL PRIMARY KEY,
    timestamp TIMESTAMP NOT NULL,
    symbol VARCHAR(20) NOT NULL,
    timeframe VARCHAR(10) NOT NULL,
    open FLOAT NOT NULL,
    high FLOAT NOT NULL,
    low FLOAT NOT NULL,
    close FLOAT NOT NULL,
    volume FLOAT NOT NULL,
    returns FLOAT,           -- Retornos simples
    log_returns FLOAT,       -- Retornos logarítmicos
    adx FLOAT,
    CONSTRAINT unique_ohlcv UNIQUE (symbol, timeframe, timestamp)
);

-- Índices para queries rápidas
CREATE INDEX idx_symbol_timeframe_timestamp ON ohlcv(symbol, timeframe, timestamp);
CREATE INDEX idx_timestamp ON ohlcv(timestamp);
```

### Consultas útiles

```sql
-- Conectar a la base de datos
psql -U trading_user -d trading_bot -h localhost

-- Ver todas las tablas
\dt

-- Contar registros totales
SELECT COUNT(*) FROM ohlcv;

-- Ver datos disponibles por símbolo
SELECT 
    symbol, 
    timeframe,
    COUNT(*) as registros,
    MIN(timestamp) as desde,
    MAX(timestamp) as hasta
FROM ohlcv 
GROUP BY symbol, timeframe
ORDER BY symbol, timeframe;

-- Ver últimos 10 registros de BTC
SELECT * FROM ohlcv 
WHERE symbol = 'BTC/USDT' AND timeframe = '1h'
ORDER BY timestamp DESC 
LIMIT 10;

-- Estadísticas de retornos
SELECT 
    symbol,
    timeframe,
    AVG(returns) as retorno_medio,
    STDDEV(returns) as volatilidad,
    MIN(returns) as peor_retorno,
    MAX(returns) as mejor_retorno
FROM ohlcv 
WHERE returns IS NOT NULL
GROUP BY symbol, timeframe;
```

### Backup de la base de datos

```bash
# Backup completo
pg_dump -U trading_user -d trading_bot -h localhost > backup_$(date +%Y%m%d).sql

# Backup solo tabla ohlcv
pg_dump -U trading_user -d trading_bot -h localhost -t ohlcv > backup_ohlcv.sql

# Restaurar desde backup
psql -U trading_user -d trading_bot -h localhost < backup.sql
```

## 📜 Scripts Disponibles

### `main.py` - Demo y Testing

```bash
python main.py
```

**Uso:** Verificar que todo funciona correctamente
**Descarga:** 1 símbolo, 1 timeframe, pocos días
**Muestra:** Pipeline completo con estadísticas detalladas

### `download_data.py` - Descarga Masiva

```bash
python download_data.py
```

**Uso:** Llenar base de datos con datos históricos
**Configurable:** Símbolos, timeframes, días
**Características:**
- Progreso en tiempo real
- Prevención de duplicados
- Manejo de errores robusto
- Resumen final con estadísticas

### `backtest.py` - Backtesting

```bash
# Backtest simple
python backtest.py

# Comparar estrategias
python backtest.py compare
```

**Uso:** Evaluar estrategias sobre datos históricos
**Características:**
- Simulación de comisiones y slippage
- Métricas detalladas de performance
- Comparación de múltiples estrategias
- Informe completo de resultados

## 🧪 Testing

### Ejecutar todos los tests

```bash
pytest tests/ -v
```

### Tests con cobertura

```bash
pytest tests/ --cov=src --cov-report=html
# Ver reporte en htmlcov/index.html
```

### Test específico

```bash
pytest tests/test_data.py::TestDataProcessor::test_clean_data_removes_duplicates -v
```

## 🗺️ Roadmap

### ✅ Fase 1: Infraestructura de Datos (COMPLETADO - Semanas 1-2)
- Sistema de descarga robusto
- Almacenamiento optimizado
- Procesamiento de datos

### ✅ Fase 2: Backtesting (COMPLETADO - Semanas 3-4)
- Motor de backtesting
- 3 estrategias implementadas
- Métricas de performance
- Sistema de comparación

### 🔄 Fase 3: Optimización y Visualización (EN PROGRESO)
- Optimización de parámetros (grid search)
- Visualizaciones de resultados
- Filtros de mercado (ADX)
- Walk-forward analysis

### 📅 Fase 4: Estrategias Avanzadas (Semanas 5-8)
- Indicadores técnicos avanzados
- Machine Learning básico
- Feature engineering
- Optimización con validación

### 📅 Fase 5: Trading Real (Semanas 9-12)
- Paper trading
- Gestión de riesgo avanzada
- Ejecución de órdenes
- Monitoreo en tiempo real

### 📅 Fase 6: Producción (Futuro)
- Dashboard web
- Alertas y notificaciones
- Multi-exchange
- Despliegue en servidor

## 🐛 Troubleshooting

### Error: "No se puede conectar a PostgreSQL"

```bash
# Verificar que está corriendo
sudo systemctl status postgresql

# Reiniciar si es necesario
sudo systemctl restart postgresql

# Verificar credenciales en config/secrets.env
```

### Error: "Invalid Api-Key ID"

**Solución:** Para datos públicos NO necesitas API keys. Deja vacíos `API_KEY` y `API_SECRET` en `config/secrets.env`.

### Error: "column does not exist"

**Solución:** Recrear la tabla:

```sql
DROP TABLE IF EXISTS ohlcv CASCADE;
```

Luego ejecutar `python main.py` para recrearla.

### Error: "duplicate key value violates unique constraint"

**Solución:** Esto es normal y esperado. El sistema previene automáticamente duplicados. Si quieres limpiar duplicados existentes:

```sql
DELETE FROM ohlcv a USING ohlcv b
WHERE a.id > b.id 
AND a.symbol = b.symbol 
AND a.timeframe = b.timeframe 
AND a.timestamp = b.timestamp;
```

### Redis no está disponible

**No es crítico.** El bot funciona sin Redis, solo perderás caché. Logs mostrarán: "Continuando sin caché."

Para instalar Redis:
```bash
sudo apt install redis-server
sudo systemctl start redis
```

### Downloads muy lentos

- Verifica tu conexión a internet
- El exchange puede tener rate limiting
- Para Binance sin API keys: ~1000 requests/min

### La descarga se queda colgada

- Presiona `Ctrl+C` para cancelar
- Revisa logs en `logs/trading_bot_*.log`
- Verifica que el exchange esté accesible

## 📝 Notas Importantes

### ⚠️ Advertencia Legal

Este bot es para **fines educativos y de investigación**. El trading conlleva riesgo financiero significativo.

**NO ejecutes trading real sin:**
1. ✅ Backtesting exhaustivo (mínimo 3-5 años de datos)
2. ✅ Paper trading extensivo (varios meses)
3. ✅ Gestión de riesgo robusta y probada
4. ✅ Comprensión completa del código y estrategias
5. ✅ Capital que puedas permitirte perder

### 🔒 Seguridad

- **NUNCA** subas `config/secrets.env` a git
- Usa contraseñas fuertes para PostgreSQL
- En producción, usa variables de entorno del sistema
- Limita permisos de archivos sensibles: `chmod 600 config/secrets.env`

### 💾 Portabilidad (Futuro)

Actualmente usa PostgreSQL (requiere instalación en cada máquina).

**Plan futuro:** Script de exportación a SQLite para portabilidad completa:
```bash
python export_to_portable.py  # Generará data/trading_bot.db
```

Esto permitirá copiar todo el proyecto en USB y ejecutar en cualquier PC.

## 🤝 Contribuir

Este es un proyecto personal de aprendizaje. Sugerencias y mejoras son bienvenidas.

## 📄 Licencia

MIT License - Usar bajo tu propio riesgo

## 📧 Contacto

Para dudas sobre el código o siguientes fases de desarrollo, consulta conmigo.

---

**Versión actual:** 0.4.0 (Semanas 1-4 completadas)  
**Última actualización:** Enero 2026  
**Python:** 3.12.3  
**PostgreSQL:** 16+  
**Datos:** 5 símbolos, 3 timeframes, ~3 años  
**Estrategias:** 3 implementadas (MA Cross, RSI, Buy&Hold)
**Research:** Optimización + ADX + Visualización
**Estado:** Research cuantitativo (NO trading real)