🐋 Leviathan — Plataforma de Análisis Cuant & Simulación de Trading

TL;DR: Plataforma de I+D cuant con tres pilares: inteligencia de mercado (whales + news + sentimiento), backtesting modular (Strategy Pattern) y gestión de riesgo basada en reglas.
API en FastAPI (puerto 8000) + front Vanilla liviano (Vite) / SPA opcional. No promete rentabilidad: está hecha para experimentar, validar y mostrar arquitectura.

---

🎯 Objetivo

• Demostrar arquitectura empresarial en sistemas financieros (asíncrono, desacoplado, testeable).
• Explorar si la fusión de señales heterogéneas (whales + news + cuant) crea edge medible.
• Ofrecer una base sólida para backtesting, simulación y, si se desea, integración live (paper/live).

---

🏛️ Arquitectura (alto nivel)

sources/            # scrapers + conectores (whales, news, exchanges)
 ├─ whales/         # streams/polling de actividad inusual
 ├─ news/           # fuentes públicas + clasificador simple
backend/            # FastAPI + servicios (market_data, risk, decision_engine)
 ├─ web/            # app FastAPI (routers, deps, middlewares)
 ├─ services/       # estrategias, validadores, riesgo, cache
 ├─ config/         # loaders y settings (.env / yaml)
 └─ tests/          # pytest (mocks, fixtures, métricas)
front-v3-vanilla/   # UI ligera (Vite + JS puro) con tests
front-v2-spa/       # (opcional) SPA (React/Vue) con componentes reutilizables
scripts/            # utilidades (arranque, semillas, verificación)
docker/             # compose para DB/API (opcional)

Backend: FastAPI (async) + WebSockets, adapters (ccxt/binance), Strategy Pattern para estrategias pluggable, riesgos y validadores.
Data: PostgreSQL (histórico/auditoría) + caché en memoria (baja latencia).
Front: Vanilla Vite (rápido, portable), SPA opcional si se requiere estado complejo.

---

🔧 Strategy Pattern: diseño y ventaja

class Strategy:
    name: str
    params: dict

    async def generate_signals(self, market_data):
        raise NotImplementedError

class RSICrossoverStrategy(Strategy):
    def __init__(self, rsi_low=30, rsi_high=70):
        self.name = "RSI_Crossover"
        self.params = {"rsi_low": rsi_low, "rsi_high": rsi_high}

    async def generate_signals(self, market_data):
        # ... calcular RSI y puntos de cruce ...
        return [{"side": "buy", "confidence": 0.62}]

# Motor de backtesting desacoplado de la estrategia
engine = BacktestEngine()
results = await engine.run_strategy_backtest(RSICrossoverStrategy(), "BTC/USDT", ...)

Ventajas

1. Extensibilidad real (agregar estrategias sin tocar el motor).
2. Métricas y reporting uniformes entre estrategias.
3. Escala a ML, multi-timeframe, optimización de hiperparámetros.
4. Mantenible: dominio separado de infraestructura/UI.

Estrategias incluidas / previstas: RSI Crossover (base), MA Cross, Bollinger, ML Predictor, Walk-Forward, multi-asset, etc.

---

🧠 Inteligencia de Mercado

• Fear & Greed (indicador externo o proxy propio).
• Whale Activity Monitor (transferencias grandes / flujos).
• News & Sentiment (API pública + clasificación básica).
• Risk Engine: reglas multi-factor con scoring.

---

✨ Features clave

• Backtesting modular (costos, slippage, sizing, métricas: Sharpe, MDD, PF, WinRate).
• Simulación (paper) y monitoreo (dashboard).
• API REST + WebSocket docs en /docs (OpenAPI/Swagger).
• Flags MOCK para correr sin APIs reales.
• Tests (pytest) y UI minimal para demo rápida.

---

🧩 Configuración — .env obligatorio

Crea backend/.env (o raíz si tu loader lo permite) con estas claves mínimas:

# ===== DATABASE =====
DATABASE_URL=postgresql://tradingbot:supersecretpassword@localhost:5433/tradingbot_db

# ===== BINANCE =====
BINANCE_API_KEY=
BINANCE_API_SECRET=
BINANCE_TESTNET=0

# ===== NEWS PROVIDER =====
NEWS_API_KEY=

# ===== LLM (DEEPSEEK R1) =====
LLM_PROVIDER=deepseek
DEEPSEEK_API_BASE=https://api.deepseek.com/v1
DEEPSEEK_API_KEY=
DEEPSEEK_MODEL=deepseek-reasoner

# ===== APP MODES =====
APP_ENV=production   # si no es 'production', el sistema puede activar MOCKs
MOCK_BINANCE=0
MOCK_NEWS=0
MOCK_KB=0

Para el front Vanilla (front-v3-vanilla/.env):

VITE_API_BASE_URL=http://127.0.0.1:8000/api

Asegurate de ejecutar load_dotenv() antes de leer variables.

---

🚀 Cómo ejecutar

Opción A — Un‑clic (Windows)

Usa start_platform.bat (incluido) para levantar todo:

• Verifica Python y dependencias.
• Activa venv y instala requirements.txt si falta.
• Levanta FastAPI en http://127.0.0.1:8000.
• (Opcional) abre el front Vanilla si detecta Vite.

Opción B — Manual (cross‑platform)

Backend

cd backend
python -m venv venv
# Windows: .\venv\Scripts\activate
# Linux/Mac: source venv/bin/activate
pip install -r requirements.txt
uvicorn web.main:app --host 127.0.0.1 --port 8000 --reload   # o app.main:app según tu módulo

Front Vanilla (recomendado para demo)

cd front-v3-vanilla
npm install
cp .env.example .env   # o crea .env con VITE_API_BASE_URL
npm run dev            # Vite en http://localhost:5173

---

🌐 Endpoints principales (API 8000)

Endpoint	Método	Descripción
/api/market-intelligence	GET	Inteligencia de mercado (FGI, whales, sentimiento)
/api/backtest	POST	Ejecuta backtest con payload de estrategia
/api/news	GET	Noticias categorizadas
/api/whale-alerts	GET	Últimas detecciones de ballenas
/health	GET	Estado del sistema
/docs	GET	Swagger/OpenAPI

---

📦 Estructura de referencia

/trading_platform/
├── backend/
│   ├── web/                # routers, deps, middlewares
│   ├── services/           # estrategias, motor, riesgo
│   ├── config/             # settings y loaders
│   ├── tests/              # pytest
│   └── main.py (opcional)  # si usas app.main:app
├── front-v3-vanilla/       # Vite + JS
├── scripts/
│   ├── start_platform.bat
│   └── verify_platform.py  # (opcional)
├── docker/
│   └── docker-compose.yml
└── README.md

---

🧰 Testing

cd backend
pytest -q

Front: unit tests a helpers (Vitest/Jest) y pruebas manuales sobre datos reales/simulados.

---

🐳 Docker (opcional)

docker/docker-compose.yml típico para DB + API:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: tradingbot
      POSTGRES_PASSWORD: supersecretpassword
      POSTGRES_DB: tradingbot_db
    ports: ["5433:5432"]
    volumes:
      - pgdata:/var/lib/postgresql/data

  api:
    build: ./backend
    env_file: ./backend/.env
    ports: ["8000:8000"]
    depends_on: [db]

volumes:
  pgdata: {}

---

🚦 Disclaimers

• Proyecto educativo/I+D. No es consejo financiero. Preferir paper trading.
• Nunca comitees secretos; usa .env y .gitignore.
• Respeta términos de servicio y rate‑limits de cada API.
• El scraping debe cumplir políticas de cada sitio.

---

📄 Licencia

MIT. Ver LICENSE.

Autor: Juan Pablo Amorosi — GitHub: https://github.com/johnitto9 — LinkedIn: https://www.linkedin.com/in/juan-pablo-amorosi-8b5894193/