🔮 XGBoost Financial Predictor — BTC/USDT

Un sistema de machine learning que aprende del comportamiento histórico del Bitcoin para anticipar si su precio subirá o bajará en las próximas 4 horas.

Ver el notebook de resultados · Documentación técnica · Instalación rápida

🎯 ¿Qué es esto?

Imagina que tienes un asistente que ha estudiado el precio del Bitcoin durante más de 3 años — cada hora, sin descanso. Ha aprendido a reconocer patrones: cómo se comporta el volumen antes de una subida, qué hace el momentum cuando el mercado va a girar.

Este proyecto es ese asistente. Le das los datos de mercado actuales y te dice: "Basándome en todo lo que he aprendido, el precio tiene un 58% de probabilidad de subir en las próximas 4 horas."

No adivina. Aprende de datos reales de la API de Binance y valida sus predicciones de forma honesta: nunca usa datos del futuro para entrenarse, y se pone a prueba período a período — igual que un trader que va mejorando con la experiencia.

✨ ¿Qué puede hacer?

📡 Descarga datos reales de Binance automáticamente — más de 28,000 velas históricas de BTC/USDT en formato horario, sin configuración manual
🧮 Calcula 37 indicadores de mercado — RSI, MACD, Bandas de Bollinger, y más; todo lo que un analista técnico calcularía a mano, pero en segundos
🎯 Predice si el precio subirá o bajará en 4 horas — con probabilidades exactas, no solo "sube" o "baja"
📉 Estima el retorno esperado — no solo la dirección, sino cuánto podría moverse
🔍 Explica cada predicción — usando SHAP, el sistema muestra qué indicadores influyeron y cuánto. No es una caja negra
✅ Se valida a sí mismo honestamente — con Walk-Forward Validation (como entrenar en el pasado y examinarse en el futuro), sin trampas estadísticas
🧪 98 tests automáticos — garantizan que cada parte del pipeline funciona correctamente

📊 Resultados — La parte más importante

🔍 ¿Qué produce el sistema?

Antes: Analizar si Bitcoin podría subir en las próximas horas requiere revisar docenas de gráficos, indicadores técnicos y el historial reciente — proceso que toma 30-60 minutos para un analista experto.

Después: El sistema analiza los mismos datos en menos de 2 segundos y entrega:

Una probabilidad de subida (ej. 0.5847 = 58.5% de probabilidad de subir)
Una señal de acción clara: COMPRA o VENTA
El retorno estimado (ej. +0.0041% en las próximas 4 horas)
Una explicación visual de por qué el modelo tomó esa decisión

📈 Métricas clave del modelo

Qué mide	Resultado	Qué significa para ti
ROC-AUC	0.5431 ± 0.028	El modelo es mejor que el azar puro (0.50) en todas las condiciones de mercado testadas
Accuracy	52.2%	De cada 100 predicciones, ~52 son correctas — supera la moneda al aire
Validación	15 períodos	Probado en 15 intervalos temporales distintos, no en uno solo
Cobertura de datos	3+ años	Entrenado con más de 28,000 horas de mercado (2023–2026)
Tests automatizados	98/98	Todo el pipeline verificado. Cero partes sin testear
Features	37 indicadores	RSI, MACD, Bollinger, OBV, retornos, volatilidad y más
Optimización	50 pruebas	Optuna buscó los mejores parámetros con inteligencia artificial

Contexto importante: Un ROC-AUC de 0.5431 puede parecer modesto, pero en mercados financieros eficientes como el de criptomonedas, superar el azar de forma consistente es extraordinariamente difícil. Los fondos de inversión cuantitativos profesionales consideran cualquier ventaja estadística como valiosa.

🖼️ Muéstrame cómo se ve

📸 [Imagen 1: Dashboard de predicciones en el notebook]

💬 Qué verías aquí: Una tabla con las últimas predicciones del sistema. Cada fila es una hora del día. Las columnas muestran: la hora, la probabilidad de subida (número entre 0 y 1), la señal recomendada en verde (COMPRA) o rojo (VENTA), y el retorno estimado en porcentaje. El formato es limpio y directo — como el panel de vuelo de un avión, mostrando solo lo esencial.

📸 [Imagen 2: Cómo fluyen los datos a través del sistema]

💬 Qué verías aquí: Un diagrama de izquierda a derecha con 9 cajas conectadas por flechas. Empieza con "Binance API" (la fuente de datos), pasa por "37 Indicadores", luego "Limpieza", "15 Períodos de Validación", "3 Modelos Baseline", "XGBoost", "Optimización", "Explicabilidad SHAP" y termina en "Modelo Final". Cada caja tiene un color diferente. Es como un plano de fábrica donde ves exactamente por dónde pasa el "producto" (los datos) hasta convertirse en una predicción.

📸 [Imagen 3: Gráfico de precio histórico de BTC con indicadores superpuestos]

💬 Qué verías aquí: Tres paneles apilados verticalmente. El más grande arriba muestra la línea del precio del Bitcoin desde 2023 hasta 2026, con una banda azul clara que marca el rango entre máximo y mínimo de cada hora — el precio fue desde ~$16,000 hasta picos de +$100,000. Abajo, un panel de barras verdes y rojas muestra el retorno diario (positivo/negativo). En el panel inferior, barras moradas muestran el volumen. Ves claramente los grandes movimientos del mercado y cómo el volumen suele explotar justo cuando el precio da un salto.

📸 [Imagen 4: Escalera de rendimiento — comparación de todos los modelos]

💬 Qué verías aquí: Un gráfico de barras con 5 barras de diferentes alturas y colores. La más corta y gris representa el "Dummy" (predicción aleatoria, AUC=0.50). Le siguen barras azul y verde para los modelos baseline. La barra naranja es XGBoost con parámetros estándar, y la barra roja más alta corresponde a XGBoost optimizado con Optuna (AUC=0.5431). Cada barra tiene una línea de error que muestra cuánto varía el resultado entre diferentes períodos. Ves claramente la jerarquía: cada modelo mejora al anterior.

📸 [Imagen 5: SHAP — Por qué el modelo tomó esta decisión]

💬 Qué verías aquí: Un gráfico horizontal de barras donde cada barra representa un indicador (feature). Las más largas corresponden a los indicadores que más influyen en las predicciones. El RSI de 7 períodos está primero, seguido del OBV con media móvil, y el retorno de las últimas 4 horas. Los colores van de azul (valor bajo del indicador) a rojo (valor alto), permitiendo ver no solo qué importa, sino en qué dirección influye. Si el RSI está muy alto (sobrecomprado), el modelo tiende a predecir bajada.

💡 Ejemplo real paso a paso

Situación: Son las 14:00 UTC del 21 de marzo de 2026. El Bitcoin está en $84,500 y quieres saber si deberías comprar o esperar.

Input — qué le das al sistema:

# Los datos llegan automáticamente de Binance.
# Son 37 números que describen el estado actual del mercado:
# RSI-14 = 52.3 (momentum neutro)
# MACD = +12.4 (tendencia alcista débil)
# Bollinger %B = 0.61 (precio en zona media-alta)
# Volumen ratio = 1.23 (volumen 23% sobre la media)
# ... y 33 indicadores más

Proceso — qué hace el sistema: El sistema consulta su "memoria" de 3 años de datos y compara el estado actual con situaciones similares del pasado. Es como preguntarle a un trader experimentado: "La última vez que el RSI estaba en 52 con este volumen, ¿qué pasó?" — pero basado en miles de ejemplos, no solo en su memoria.

Output — qué te devuelve:

Timestamp              P(sube)     Señal      Retorno pred
2026-03-21 14:00 UTC   0.5847     COMPRA      +0.0041%
2026-03-21 13:00 UTC   0.4923     VENTA       -0.0018%
2026-03-21 12:00 UTC   0.5312     COMPRA      +0.0022%

Conclusión: El modelo asigna un 58.5% de probabilidad de subida. No es una certeza — el mercado nunca lo es — pero es una ventaja estadística medible. Un sistema de trading cuantitativo usaría esta señal dentro de una estrategia de gestión de riesgo más amplia.

🛠️ ¿Cómo está construido?

Stack tecnológico

Tecnología	Para qué sirve	Versión
Python	Lenguaje base de todo el proyecto	3.10+
XGBoost	El modelo principal que aprende a predecir (como un árbol de decisiones muy sofisticado)	2.0+
scikit-learn	Herramientas de ML estándar: métricas, preprocesamiento, modelos baseline	1.3+
Optuna	Busca automáticamente los mejores parámetros para XGBoost (optimización bayesiana)	3.4+
SHAP	Explica por qué el modelo tomó cada decisión (como una auditoría de la IA)	0.43+
pandas	Manipulación de datos tabulares (como Excel, pero para millones de filas)	2.0+
numpy	Cálculos matemáticos rápidos sobre arrays de números	1.24+
matplotlib / seaborn	Generación de gráficos y visualizaciones	3.7+ / 0.12+
pyarrow	Lectura/escritura eficiente de archivos .parquet (formato de datos comprimido)	14.0+
requests	Llamadas a la API de Binance para descargar datos	2.31+
joblib	Serialización del modelo (guardarlo como un archivo reutilizable)	1.3+
pytest	Framework de testing automático (98 tests)	7.4+

Arquitectura del pipeline

flowchart TD
    A[🌐 Binance API\nOHLCV 1h] -->|fase_01_ingesta.py| B[📦 Raw Data\n28,222 velas]
    B -->|fase_02_features.py| C[🔧 Feature Engineering\n37 indicadores]
    C -->|fase_03_target.py| D[🎯 Target\nRetorno 4h futuro]
    D -->|fase_04_preparacion.py| E[🧹 Dataset limpio\n+ 15 folds WF]
    E -->|fase_05_baseline.py| F[📊 Baselines\nDummy · LR · RF]
    E -->|fase_06_xgboost.py| G[⚡ XGBoost Default\nAUC 0.5266]
    G -->|fase_07_optuna.py| H[🔍 Optuna\n50 trials · AUC 0.5431]
    H -->|fase_08_shap.py| I[🔮 SHAP\n10 visualizaciones]
    H -->|fase_09_serializacion.py| J[💾 Modelo Final\npkl + JSON + metadata]
    F --> K{📈 Comparación}
    G --> K
    H --> K
    K --> L[🏆 AUC: 0.5431\n98/98 tests ✅]

Validación honesta: Walk-Forward

Fold  0: [====TRAIN 17,280 velas====] [TEST 720]
Fold  1: [======TRAIN 18,000 velas======] [TEST 720]
Fold  2: [========TRAIN 18,720 velas========] [TEST 720]
...
Fold 14: [==================TRAIN 27,360 velas==================] [TEST 720]
                                          ↑
                          El test NUNCA ve datos del futuro

Cada período de test es una situación de mercado que el modelo nunca vio durante el entrenamiento. Esto garantiza que las métricas reportadas son realistas, no infladas.

📁 Estructura del proyecto

xgboost-financial-predictor/
│
├── 📄 config.py                    ← Fuente única de verdad: símbolos, parámetros, rutas
├── 📄 requirements.txt             ← Dependencias con versiones mínimas
│
├── 📂 scripts/                     ← Pipeline modular: un script por fase
│   ├── fase_01_ingesta.py          ← Descarga datos de Binance (paginado, rate-limit aware)
│   ├── fase_02_features.py         ← Calcula 37 indicadores (RSI, MACD, OBV, etc.)
│   ├── fase_03_target.py           ← Define el target: retorno log a 4h
│   ├── fase_04_preparacion.py      ← Limpia NaN, genera 15 folds Walk-Forward
│   ├── fase_05_baseline.py         ← Entrena Dummy, LogReg y Random Forest
│   ├── fase_06_xgboost.py          ← XGBoost con parámetros por defecto
│   ├── fase_07_optuna.py           ← Optimización bayesiana (50 trials)
│   ├── fase_08_shap.py             ← Explicabilidad: 10 visualizaciones SHAP
│   └── fase_09_serializacion.py    ← Guarda modelo final + metadata
│
├── 📂 tests/                       ← 98 tests automáticos (pytest)
│   ├── conftest.py                 ← Fixtures compartidos (carga artefactos)
│   ├── test_fase_01.py             ← 11 tests: integridad de datos crudos
│   ├── test_fase_02.py             ← 13 tests: correctitud de features
│   ├── test_fase_03.py             ← 8 tests: target sin data leakage
│   ├── test_fase_04.py             ← 11 tests: splits WF sin solapamiento
│   ├── test_fase_05.py             ← 7 tests: baselines razonables
│   ├── test_fase_06.py             ← 9 tests: XGBoost supera baseline
│   ├── test_fase_07.py             ← 8 tests: Optuna mejora el default
│   ├── test_fase_08.py             ← 10 tests: SHAP values válidos
│   ├── test_fase_09.py             ← 10 tests: reproducibilidad pkl ↔ JSON
│   └── test_integracion.py         ← 11 tests: pipeline end-to-end
│
├── 📂 data/
│   ├── raw/                        ← Fase 1: datos crudos de Binance
│   ├── features/                   ← Fases 2-3: con indicadores y target
│   ├── prepared/                   ← Fase 4: dataset limpio + splits JSON
│   └── results/                    ← Fases 5-8: métricas, predicciones, SHAP
│
├── 📂 models/                      ← Artefactos finales del modelo
│   ├── xgboost_clf.pkl             ← Clasificador (formato joblib)
│   ├── xgboost_clf.json            ← Clasificador (formato nativo XGBoost)
│   ├── xgboost_reg.pkl             ← Regresor (formato joblib)
│   ├── xgboost_reg.json            ← Regresor (formato nativo XGBoost)
│   └── model_metadata.json         ← Features, params, métricas, versiones
│
├── 📂 plots/shap/                  ← 10 visualizaciones SHAP generadas
│
├── 📂 notebooks/
│   └── resumen_proyecto_06.ipynb   ← Informe completo ejecutable (28 celdas)
│
└── 📂 docs/images/                 ← Imágenes para este README

🚀 Instalación

Prerrequisitos

Python 3.10+ — Descargar aquí
pip — Incluido con Python
Conexión a internet — Para la descarga de datos de Binance (Fase 1)
4 GB de RAM mínimo recomendado
500 MB de espacio en disco para datos y modelos

Pasos

# 1. Clonar o descargar el proyecto
git clone <url-del-repositorio>
cd xgboost-financial-predictor

# 2. (Recomendado) Crear entorno virtual
python -m venv venv
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows

# 3. Instalar dependencias
pip install -r requirements.txt

# 4. Verificar la instalación
python -c "import xgboost, shap, optuna; print('Todo instalado correctamente')"

# 5. Verificar los tests (opcional, requiere datos generados primero)
pytest tests/test_fase_01.py -v --co  # Ver qué tests existen

▶️ Cómo usarlo

En lenguaje simple (3 pasos)

Descarga los datos: El sistema va a Binance y recoge 3 años de historial del Bitcoin
Aprende los patrones: Procesa 37 indicadores y encuentra qué señales predicen movimientos
Hace predicciones: Con el modelo entrenado, te dice la probabilidad de subida para la siguiente ventana de 4 horas

Comandos técnicos — ejecución completa del pipeline

# FASE 1 — Descarga datos de Binance (~5 minutos, 29 requests API)
python scripts/fase_01_ingesta.py
pytest tests/test_fase_01.py -v  # ✅ 11 tests

# FASE 2 — Calcula 37 indicadores técnicos (~30 segundos)
python scripts/fase_02_features.py
pytest tests/test_fase_02.py -v  # ✅ 13 tests

# FASE 3 — Define el target de 4h (~10 segundos)
python scripts/fase_03_target.py
pytest tests/test_fase_03.py -v  # ✅ 8 tests

# FASE 4 — Limpia datos y genera 15 folds Walk-Forward (~20 segundos)
python scripts/fase_04_preparacion.py
pytest tests/test_fase_04.py -v  # ✅ 11 tests

# FASE 5 — Entrena 3 modelos baseline (~3 minutos)
python scripts/fase_05_baseline.py
pytest tests/test_fase_05.py -v  # ✅ 7 tests

# FASE 6 — XGBoost con parámetros por defecto (~5 minutos)
python scripts/fase_06_xgboost.py
pytest tests/test_fase_06.py -v  # ✅ 9 tests

# FASE 7 — Optimización Optuna: 50 trials (~20-40 minutos)
python scripts/fase_07_optuna.py
pytest tests/test_fase_07.py -v  # ✅ 8 tests

# FASE 8 — Análisis SHAP y 10 visualizaciones (~2 minutos)
python scripts/fase_08_shap.py
pytest tests/test_fase_08.py -v  # ✅ 10 tests

# FASE 9 — Serializar modelo final (~30 segundos)
python scripts/fase_09_serializacion.py
pytest tests/test_fase_09.py -v  # ✅ 10 tests

# COMPROBACIÓN FINAL — Integración completa
pytest tests/test_integracion.py -v  # ✅ 11 tests

# TODAS LAS FASES DE UNA VEZ
pytest tests/ -v  # ✅ 98/98 tests

Usar el modelo ya entrenado

import joblib
import json
import pandas as pd
from config import ALL_FEATURES

# Cargar el modelo (no necesitas reentrenar)
clf = joblib.load("models/xgboost_clf.pkl")
reg = joblib.load("models/xgboost_reg.pkl")

# Cargar los datos más recientes (ya procesados en Fase 4)
df = pd.read_parquet("data/prepared/btcusdt_1h_clean.parquet")

# Predecir en las últimas 5 horas
X_reciente = df[ALL_FEATURES].tail(5)
probabilidades = clf.predict_proba(X_reciente)[:, 1]
retorno_esperado = reg.predict(X_reciente)

for i, (prob, ret) in enumerate(zip(probabilidades, retorno_esperado)):
    senal = "COMPRA" if prob >= 0.5 else "VENTA"
    print(f"Hora -{4-i}: P(sube)={prob:.4f} | {senal} | Ret. estimado: {ret*100:.4f}%")

🧪 Tests

El proyecto cuenta con 98 tests automáticos organizados por fases. Siguen el principio de que ninguna fase avanza si la anterior falla.

# Ejecutar todos los tests
pytest tests/ -v

# Ejecutar solo una fase
pytest tests/test_fase_07.py -v

# Con reporte de resultados detallado
pytest tests/ -v --tb=short

# Ver cuántos tests tiene cada módulo
pytest tests/ --collect-only -q

Cobertura de tests por fase

Módulo	Tests	Qué verifica
`test_fase_01.py`	11	Datos crudos: tipos, gaps, rangos OHLC, mínimo de filas
`test_fase_02.py`	13	Features: RSI en [0,100], ATR positivo, sin infinitos
`test_fase_03.py`	8	Target: binario, balanceado, sin data leakage
`test_fase_04.py`	11	Walk-Forward: sin solapamiento, expanding window
`test_fase_05.py`	7	Baselines: AUC en rango válido, 3 modelos presentes
`test_fase_06.py`	9	XGBoost: supera dummy, probabilidades en [0,1]
`test_fase_07.py`	8	Optuna: parámetros en rango, no sobreajuste
`test_fase_08.py`	10	SHAP: forma correcta, finitos, plots existen
`test_fase_09.py`	10	Serialización: pkl≡JSON, metadata completa
`test_integracion.py`	11	Pipeline completo: flujo de datos, sin leakage global

🤝 ¿Quieres contribuir?

Consulta CONTRIBUTING.md para la guía completa. Resumen rápido:

# 1. Fork del repositorio
# 2. Crear rama para tu feature
git checkout -b feature/nombre-descriptivo

# 3. Hacer cambios y asegurarte de que los tests pasan
pytest tests/ -v

# 4. Commit con mensaje descriptivo
git commit -m "feat: descripción clara del cambio"

# 5. Pull Request al repositorio principal

Regla principal: Toda modificación en scripts/ debe venir acompañada de tests en tests/. El pipeline no acepta PRs que bajen la cobertura de tests.

🗓️ Historial de cambios

Consulta CHANGELOG.md para el historial completo de versiones.

👤 Autor

Desarrollado como proyecto de Data Engineering & Machine Learning aplicado a mercados financieros.

Stack: Python · XGBoost · Optuna · SHAP · pytest
Metodología: Walk-Forward Validation · Bayesian Optimization · Explainable AI
Datos: Binance API (pública, sin autenticación)

📄 Licencia

Este proyecto está bajo la Licencia MIT — puedes usarlo, modificarlo y distribuirlo libremente, citando la fuente original.

"Un sistema honesto que aprende del mercado sin engañarse a sí mismo."

Pipeline completo · 9 fases · 98 tests · 37 indicadores · 15 folds · AUC 0.5431

Navigation Menu

Repository navigation

About

Repository files navigation

🔮 XGBoost Financial Predictor — BTC/USDT

🎯 ¿Qué es esto?

✨ ¿Qué puede hacer?

📊 Resultados — La parte más importante

🔍 ¿Qué produce el sistema?

📈 Métricas clave del modelo

🖼️ Muéstrame cómo se ve

💡 Ejemplo real paso a paso

🛠️ ¿Cómo está construido?

Stack tecnológico

Arquitectura del pipeline

Validación honesta: Walk-Forward

📁 Estructura del proyecto

🚀 Instalación

Prerrequisitos

Pasos

▶️ Cómo usarlo

En lenguaje simple (3 pasos)

Comandos técnicos — ejecución completa del pipeline

Usar el modelo ya entrenado

🧪 Tests

Cobertura de tests por fase

🤝 ¿Quieres contribuir?

🗓️ Historial de cambios

👤 Autor

📄 Licencia

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
__pycache__		__pycache__
data		data
docs/images		docs/images
models		models
notebooks		notebooks
plots/shap		plots/shap
scripts		scripts
tests		tests
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
config.py		config.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

🔮 XGBoost Financial Predictor — BTC/USDT

🎯 ¿Qué es esto?

✨ ¿Qué puede hacer?

📊 Resultados — La parte más importante

🔍 ¿Qué produce el sistema?

📈 Métricas clave del modelo

🖼️ Muéstrame cómo se ve

💡 Ejemplo real paso a paso

🛠️ ¿Cómo está construido?

Stack tecnológico

Arquitectura del pipeline

Validación honesta: Walk-Forward

📁 Estructura del proyecto

🚀 Instalación

Prerrequisitos

Pasos

▶️ Cómo usarlo

En lenguaje simple (3 pasos)

Comandos técnicos — ejecución completa del pipeline

Usar el modelo ya entrenado

🧪 Tests

Cobertura de tests por fase

🤝 ¿Quieres contribuir?

🗓️ Historial de cambios

👤 Autor

📄 Licencia

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages