El usuario pregunta en español cómo construir desde cero un repositorio definitivo de laboratorio quant sin gastar nada, hasta tener un bot listo para ejecutar. Voy a responder en español organizando un plan práctico y completo, empezando por la filosofía y arquitectura general del repositorio. Luego pienso en el stack tecnológico 100% gratuito, fuentes de datos libres, la estructura del repositorio con CI/CD, la capa de datos y validación, investigación con etiquetado y tracking de experimentos, backtesting riguroso con validación estadística (walk-forward, CPCV, deflated Sharpe), construcción de portafolio y gestión de riesgo, hasta llegar a la capa de ejecución con trading en papel, operación en vivo con logging y alertas. Planeo armar una respuesta organizada con código concreto: pyproject.toml, árbol de directorios, interfaz de estrategia, configuración con pydantic, motor de backtesting, workflow de GitHub Actions, Dockerfile, alertas por Telegram y validación CPCV, usando infraestructura verdaderamente gratuita como Oracle Cloud Always Free y GitHub Actions. Para monitoreo y persistencia gratuita pienso en Cloudflare Tunnel para exponer dashboards, Grafana Cloud o self-host, MLflow local con DVC respaldado en Backblaze B2, y preferir SQLite/DuckDB con litestream en vez de Postgres gestionado que puede dormirse. Para datos de mercado, Binance Vision, Bybit, OKX e Hyperliquid ofrecen históricos completos gratis, y CCXT sirve para datos en vivo. Para equities tengo varias fuentes gratuitas como Stooq, yfinance, Alpaca, Tiingo, Finnhub, SEC EDGAR con datos XBRL point-in-time, factores de Fama-French y FRED para macro; para futuros y FX, Dukascopy y HistData.com ofrecen tick y M1 gratis, mientras reviso los datos fundamentales point-in-time de SEC XBRL. El problema más grande que identifico es la supervivencia y acciones corporativas: no hay buena fuente gratuita (CRSP es de pago), así que planeo recomendar usar ETFs/índices, criptomonedas, universos líquidos y aplicar descuentos de precaución como solución. También estoy listando brokers con paper trading gratuito (Alpaca, Binance testnet, Bybit testnet, Hyperliquid testnet, IBKR paper, OANDA demo, Tradovate demo) para que el usuario pueda probar estrategias sin riesgo real. Ahora estructuro la respuesta en fases (Fase 0 a Fase 7), junto con el árbol del repositorio, archivos clave y un plan de 6-8 semanas. Voy a incluir código mínimo pero funcional para varios componentes: la configuración del proyecto, el árbol del repositorio, un protocolo de estrategia base, configuración vía pydantic-settings y YAML, ingestión de datos desde Binance Vision, consultas al catálogo con DuckDB, modelo de costos, validación cruzada purgada (CPCV), ratio de Sharpe deflactado, el esqueleto del runner en vivo con estado y órdenes idempotentes, CI con GitHub Actions, Dockerfile y compose, servicio systemd, y alertas por Telegram con un sistema de vigilancia tipo "dead man switch". No todo necesita estar completo: mostraré los componentes clave en detalle y esbozaré el resto, equilibrando profundidad con extensión. También añadiré una nota aclarando que esto es con fines educativos, no asesoría financiera. Quiero enfatizar que el trading en papel debe venir primero, y plantear la idea central de "un solo contrato": el mismo objeto de estrategia debe ejecutarse tanto en backtest como en producción, sin lógica duplicada — esta es la decisión arquitectónica más importante de todas. También debo mencionar el determinismo, las semillas aleatorias, el congelamiento de timestamps, la ausencia de look-ahead por construcción (joins as-of, shifts), la semántica de ejecución al cierre de barra, comisiones y funding, y la prueba de paridad investigación-producción (reproducir ticks en vivo a través del backtester y comparar resultados). Ahora estoy estructurando el documento: empezando con las decisiones arquitectónicas fundamentales, luego el stack gratuito en formato tabla, los datos gratuitos disponibles (y lo que no se puede conseguir gratis), y continuando con las siguientes secciones. Voy a esbozar el resto del índice: la estructura del repositorio, la capa de datos, la capa de investigación, el motor de backtest, la validación estadística, portfolio y riesgo, ejecución, infraestructura en vivo gratuita, un plan de ocho semanas, y un checklist final de condiciones para no desplegar. Escribiré todo en español, con un tono técnico, usando tablas y código, manteniendo una extensión razonable. # Quant Lab desde cero, coste 0 € Te lo doy como lo construiría yo hoy: decisiones de arquitectura primero (que es donde se gana o se pierde), luego el scaffolding real, y al final el bot corriendo en un VPS gratuito con alertas. --- ## 0. Las 5 decisiones que determinan todo lo demás Antes de escribir una línea, fija esto. Cambiarlo después cuesta semanas. | Decisión | Mi elección | Por qué | |---|---|---| | **1. Un solo código para backtest y live** | La estrategia es un objeto que recibe `on_bar(state) -> target_positions`. El motor cambia; la estrategia **nunca**. | El 90% de las pérdidas inexplicables vienen de tener dos implementaciones que divergen. | | **2. Target weights, no órdenes** | La estrategia emite *posición objetivo* (p. ej. `{"BTCUSDT": 0.35}`). El OMS calcula el delta y rutea. | Hace la estrategia idempotente y testeable. Si el bot se cae y reinicia, converge sola al estado correcto. | | **3. Lago de datos inmutable + vistas** | Parquet particionado en disco + DuckDB como motor de consulta. Nada de CSVs sueltos ni de llamar a la API en el backtest. | Reproducibilidad. Y DuckDB te da SQL sobre 50 GB en un portátil. | | **4. Mercado inicial** | **Cripto perpetuos** (Binance/Bybit) para el primer ciclo completo. | Datos históricos gratis y completos (tick-level), sin survivorship bias, sin corporate actions, testnet real, 24/7, API sin coste. Es el único activo donde un laboratorio gratuito es *honesto*. Equities los añades en fase 2. | | **5. Reloj de eventos** | Todo con timestamps UTC en nanosegundos, y **ejecución en el cierre de la barra siguiente** a la señal. | Elimina por construcción el look-ahead más común. | > Regla de oro que vas a tatuarte: *si no puedo reconstruir exactamente el estado que la estrategia veía en el instante T usando solo datos con `available_at <= T`, no es un backtest, es ficción.* --- ## 1. Stack 100 % gratis ``` Lenguaje Python 3.11/3.12 Entorno uv (astral) — 10-100x más rápido que pip/poetry Datos Polars + DuckDB + PyArrow (Parquet) Backtest Motor propio vectorizado (research) + nautilus_trader o vectorbt (validación cruzada) ML scikit-learn, LightGBM, PyTorch (CPU) — Colab gratis si necesitas GPU Experimentos MLflow local (sqlite backend) + DVC para datasets Exchanges ccxt (unificado) + SDK nativo del exchange principal Validación pandera (esquemas), hypothesis (property testing) Calidad ruff + mypy + pytest + pre-commit CI GitHub Actions (2000 min/mes gratis) Contenedor Docker + docker compose Hosting Oracle Cloud Always Free (4 vCPU ARM / 24 GB RAM, para siempre) Observabilidad Prometheus + Grafana (self-host) o Grafana Cloud free Alertas Telegram Bot API + healthchecks.io (dead man's switch) Secretos SOPS + age (cifrado en el repo) o variables de entorno en el VPS Backups restic → Backblaze B2 (10 GB gratis) ``` --- ## 2. Datos gratis: qué sí y qué no **Lo que consigues de verdad gratis:** | Fuente | Qué da | Nota | |---|---|---| | `data.binance.vision` | Klines 1m, aggTrades, trades, bookTicker, funding — **desde 2017, histórico completo, ZIP diarios/mensuales** | La joya de la corona. Descarga directa HTTP, sin API key. | | Bybit / OKX public data | Trades y klines históricos | Para cross-check de un segundo venue. | | Hyperliquid API | Order book L2, fills, funding | DEX perp, API abierta. | | SEC EDGAR + *Financial Statement Data Sets* | Fundamentales USA con **fecha de publicación** → point-in-time real | Trimestral, desde 2009. Lo único verdaderamente PIT y gratis en equities. | | Stooq / Nasdaq Data Link | EOD acciones, índices, FX | Stooq es sorprendentemente limpio para daily. | | Dukascopy (`dukascopy-node`) | **Tick FX y CFDs desde 2003** | Gratis, enorme, ideal para FX. | | Ken French Data Library | Factores (MKT, SMB, HML, MOM, QMJ...) | Para atribución de tu PnL. | | FRED | Macro, tipos, spreads de crédito | API key gratis. | | Alpaca free tier | Paper trading + histórico 5 años | Para el módulo de equities. | **Lo que NO consigues gratis (y cómo lo gestionas):** - **Universo sin survivorship bias en equities** → por eso empiezas en cripto. Cuando pases a equities, usa ETFs/índices líquidos o acepta un *haircut* explícito del 20-40 % en el Sharpe y documéntalo. - **Order book histórico profundo multi-nivel** → usa `bookTicker` (L1) de Binance Vision y modela el impacto con un modelo paramétrico (raíz cuadrada), no con datos. - **Datos de préstamo/short interest** → no shortees equities en el laboratorio v1. - **Tick data de futuros CME** → Databento tiene créditos iniciales gratuitos; úsalos para un estudio puntual, no para el pipeline. --- ## 3. Scaffolding del repositorio ### 3.1 Estructura ``` quantlab/ ├── pyproject.toml ├── Makefile ├── .pre-commit-config.yaml ├── .github/workflows/ci.yml ├── docker/ │ ├── Dockerfile │ └── compose.yml ├── conf/ # configuración declarativa, NADA de magic numbers en código │ ├── base.yaml │ ├── universe/crypto_perp_top20.yaml │ ├── strategy/xsec_momentum.yaml │ ├── costs/binance_futures.yaml │ └── live/prod.yaml ├── src/quantlab/ │ ├── core/ │ │ ├── types.py # Bar, Fill, Order, Position (dataclasses frozen) │ │ ├── clock.py # SimClock / LiveClock — misma interfaz │ │ └── config.py # pydantic-settings │ ├── data/ │ │ ├── sources/ │ │ │ ├── binance_vision.py │ │ │ ├── ccxt_live.py │ │ │ └── sec_edgar.py │ │ ├── lake.py # read/write parquet particionado │ │ ├── catalog.py # DuckDB: vistas, as-of joins │ │ └── schemas.py # pandera │ ├── features/ │ │ ├── registry.py # @feature decorator │ │ └── technical.py, microstructure.py, cross_sectional.py │ ├── labels/ │ │ └── triple_barrier.py │ ├── strategy/ │ │ ├── base.py # Protocol Strategy │ │ └── xsec_momentum.py │ ├── backtest/ │ │ ├── engine.py # event loop │ │ ├── costs.py # fees + slippage + funding + impacto │ │ └── metrics.py │ ├── validation/ │ │ ├── cv.py # PurgedKFold, CPCV │ │ ├── deflated.py # DSR, PBO │ │ └── monte_carlo.py │ ├── portfolio/ │ │ ├── sizing.py # vol targeting, Kelly fraccional │ │ └── risk.py # límites, kill switches │ ├── execution/ │ │ ├── oms.py # target weights → órdenes, idempotente │ │ ├── adapters/binance.py │ │ ├── adapters/paper.py │ │ └── reconcile.py │ ├── live/ │ │ ├── runner.py # el bot │ │ ├── state.py # SQLite persistente │ │ └── alerts.py # Telegram │ └── cli.py # typer: ql ingest / research / backtest / live ├── tests/ │ ├── unit/ │ ├── property/ # hypothesis │ └── golden/ # backtests congelados que no pueden cambiar ├── notebooks/ # SOLO exploración, jupytext → .py └── reports/ ``` ### 3.2 `pyproject.toml` ```toml [project] name = "quantlab" version = "0.1.0" requires-python = ">=3.11" dependencies = [ "polars>=1.0", "duckdb>=1.0", "pyarrow>=16", "numpy", "scipy", "pandas", "pandera[polars]", "pydantic>=2", "pydantic-settings", "ccxt", "httpx", "tenacity", "typer", "rich", "structlog", "scikit-learn", "lightgbm", "mlflow", "matplotlib", ] [project.optional-dependencies] dev = ["pytest", "pytest-cov", "hypothesis", "ruff", "mypy", "pre-commit", "jupytext", "nbstripout"] [project.scripts] ql = "quantlab.cli:app" [tool.ruff] line-length = 100 lint.select = ["E","F","I","UP","B","SIM","NPY","PD","RUF"] [tool.mypy] strict = true ignore_missing_imports = true [tool.pytest.ini_options] addopts = "-q --strict-markers" markers = ["slow", "network"] ``` ### 3.3 `Makefile` (tu interfaz humana) ```makefile .PHONY: setup lint test ingest research backtest live setup: uv venv && uv pip install -e ".[dev]" && uv run pre-commit install lint: uv run ruff check . && uv run ruff format --check . && uv run mypy src test: uv run pytest tests/unit tests/property -m "not network" golden: uv run pytest tests/golden ingest: uv run ql ingest klines --universe crypto_perp_top20 --start 2019-01-01 backtest: uv run ql backtest --config conf/strategy/xsec_momentum.yaml live: uv run ql live --config conf/live/prod.yaml --mode paper ``` ### 3.4 `.pre-commit-config.yaml` ```yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.6.9 hooks: [{id: ruff, args: [--fix]}, {id: ruff-format}] - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: check-added-large-files # que nadie commitee parquets args: [--maxkb=500] - id: detect-private-key - id: end-of-file-fixer - repo: https://github.com/kynan/nbstripout rev: 0.7.1 hooks: [{id: nbstripout}] ``` ### 3.5 CI gratis (`.github/workflows/ci.yml`) ```yaml name: ci on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v3 - run: uv python install 3.12 - run: uv pip install --system -e ".[dev]" - run: ruff check . && mypy src - run: pytest tests/unit tests/property -m "not network" --cov=src - run: pytest tests/golden # <- el guardián anti-regresión ``` --- ## 4. Capa de datos ### 4.1 Ingesta (ejemplo real: Binance Vision) ```python # src/quantlab/data/sources/binance_vision.py import httpx, io, zipfile, polars as pl from tenacity import retry, stop_after_attempt, wait_exponential BASE = "https://data.binance.vision/data/futures/um/monthly/klines" COLS = ["open_time","open","high","low","close","volume","close_time", "quote_volume","trades","taker_buy_base","taker_buy_quote","ignore"] @retry(stop=stop_after_attempt(5), wait=wait_exponential(min=1, max=30)) def fetch_month(symbol: str, interval: str, ym: str) -> pl.DataFrame: url = f"{BASE}/{symbol}/{interval}/{symbol}-{interval}-{ym}.zip" r = httpx.get(url, timeout=60.0) if r.status_code == 404: return pl.DataFrame(schema={c: pl.Utf8 for c in COLS}) r.raise_for_status() with zipfile.ZipFile(io.BytesIO(r.content)) as z: name = z.namelist()[0] df = pl.read_csv(z.read(name), has_header=False, new_columns=COLS) return ( df.with_columns( ts=pl.col("open_time").cast(pl.Int64).cast(pl.Datetime("ms")).dt.replace_time_zone("UTC"), symbol=pl.lit(symbol), ) .select("ts","symbol", pl.col(["open","high","low","close","volume","quote_volume"]).cast(pl.Float64), pl.col("trades").cast(pl.Int64), pl.col("taker_buy_base").cast(pl.Float64)) .sort("ts") ) ``` ### 4.2 El lago ``` data/lake/ bars/interval=1m/symbol=BTCUSDT/year=2024/month=03/part.parquet funding/symbol=BTCUSDT/... universe/snapshot_date=2024-03-01/members.parquet # <- universo PIT ``` Particionado por `symbol/year/month`, compresión `zstd`. Nunca sobrescribes: reingestas a un directorio nuevo y mueves un puntero. ### 4.3 Catálogo con DuckDB ```python # src/quantlab/data/catalog.py import duckdb from pathlib import Path class Catalog: def __init__(self, lake: Path, db: Path = Path("data/catalog.duckdb")): self.con = duckdb.connect(str(db)) self.con.execute(f""" CREATE OR REPLACE VIEW bars AS SELECT * FROM read_parquet('{lake}/bars/**/*.parquet', hive_partitioning=1); """) def bars(self, symbols: list[str], start: str, end: str, interval="1m"): return self.con.execute(""" SELECT ts, symbol, open, high, low, close, volume FROM bars WHERE interval = ? AND symbol IN ? AND ts >= ? AND ts < ? ORDER BY ts, symbol """, [interval, symbols, start, end]).pl() ``` ### 4.4 Validación obligatoria al ingerir ```python # src/quantlab/data/schemas.py import pandera.polars as pa class BarSchema(pa.DataFrameModel): ts: pa.typing.Series[pa.DateTime] symbol: str open: float = pa.Field(gt=0) high: float = pa.Field(gt=0) low: float = pa.Field(gt=0) close: float = pa.Field(gt=0) volume: float = pa.Field(ge=0) @pa.dataframe_check def ohlc_consistent(cls, df): return (df["high"] >= df["low"]) & (df["high"] >= df["close"]) & (df["low"] <= df["close"]) ``` Y un **informe de calidad** por símbolo: gaps de barras, duplicados, saltos de precio > N σ, volúmenes cero. Si falla, el pipeline **para**. Los datos sucios silenciosos son la causa número 1 de estrategias fantasma. ### 4.5 Point-in-time por diseño Toda tabla que no sea precio lleva **dos timestamps**: `event_time` (cuándo ocurrió) y `available_at` (cuándo lo supiste). Las uniones son siempre `ASOF JOIN ... ON available_at <= bar.ts`. Esto es lo que mata el look-ahead en fundamentales, universos, y cualquier dato revisado. --- ## 5. Capa de research ### 5.1 Features como registro, no como spaghetti ```python # src/quantlab/features/registry.py from collections.abc import Callable import polars as pl REGISTRY: dict[str, Callable] = {} def feature(name: str, lookback: int): def deco(fn): fn.lookback = lookback # crítico para el purging en CV REGISTRY[name] = fn return fn return deco @feature("mom_20", lookback=20) def mom_20(df: pl.DataFrame) -> pl.Expr: return (pl.col("close") / pl.col("close").shift(20) - 1).over("symbol") ``` Que cada feature **declare su lookback** no es cosmético: lo necesitas para purgar correctamente en validación cruzada. ### 5.2 Etiquetado (si haces ML) Triple barrier de López de Prado + *meta-labeling*: un modelo primario genera la señal, un segundo modelo decide si operarla. Mucho más robusto que predecir retornos directamente. ### 5.3 Experimentos MLflow local con backend SQLite. Cada run registra: hash de git, hash del dataset (DVC), config completa, seeds, métricas in/out-of-sample, y los artefactos del equity curve. **Si un resultado no está en MLflow, no existe.** ### 5.4 Notebooks `jupytext` para que todo notebook tenga un `.py` espejo versionable + `nbstripout` en pre-commit. Los notebooks son para mirar; nada que viva en un notebook puede entrar en producción. Cuando algo funciona, se migra a `src/` con tests. --- ## 6. Backtesting ### 6.1 El contrato de la estrategia ```python # src/quantlab/strategy/base.py from typing import Protocol import polars as pl class Strategy(Protocol): warmup: int # barras necesarias antes de operar def on_bar(self, ctx: "Context") -> dict[str, float]: """Devuelve pesos objetivo por símbolo. Suma |w| <= gross_limit. NO puede acceder a nada fuera de ctx. ctx solo expone datos <= ctx.now.""" ... ``` El `Context` es la *única* puerta a los datos y está blindado: internamente hace slicing hasta `now`. Así el look-ahead es imposible, no solo improbable. ### 6.2 Modelo de costes — aquí se gana o se pierde ```python # src/quantlab/backtest/costs.py from dataclasses import dataclass @dataclass(frozen=True) class CostModel: taker_bps: float = 4.5 # Binance futures taker maker_bps: float = 1.8 half_spread_bps: float = 1.0 impact_coef: float = 0.35 # k en el modelo raíz funding: bool = True def cost_bps(self, notional: float, adv: float, is_taker=True) -> float: fee = self.taker_bps if is_taker else self.maker_bps participation = notional / max(adv, 1.0) impact = self.impact_coef * 1e4 * (participation ** 0.5) return fee + self.half_spread_bps + impact ``` Añade: **funding de perpetuos** (puede ser el 100 % del PnL en estrategias de carry), latencia (señal en cierre de barra t → ejecución en t+1), y **fills parciales**. Regla práctica: si tu estrategia no sobrevive a costes 3× los reales, no es una estrategia. ### 6.3 Tests golden Congelas 3-5 backtests de referencia con su equity curve hasheada. Si un refactor cambia el resultado, el CI falla. Esto te salva de romper silenciosamente el motor. ### 6.4 Test de paridad research ↔ producción Grabas 1 semana de datos live (todos los eventos, con timestamps de recepción), los reproduces por el backtester y comparas posiciones barra a barra. Tolerancia < 1e-6. **Sin este test no despliegas.** Es el que descubre los bugs que cuestan dinero. --- ## 7. Validación estadística: el módulo anti-autoengaño Esto es lo que separa un laboratorio de un generador de ilusiones. ```python # src/quantlab/validation/cv.py import numpy as np def purged_kfold(n: int, n_splits: int, embargo: float = 0.01, horizon: int = 1): """Purga las muestras cuyas etiquetas se solapan con el test + embargo temporal.""" idx = np.arange(n) folds = np.array_split(idx, n_splits) emb = int(n * embargo) for f in folds: lo, hi = f[0], f[-1] train = idx[(idx < lo - horizon) | (idx > hi + horizon + emb)] yield train, f ``` ```python # src/quantlab/validation/deflated.py import numpy as np from scipy.stats import norm def deflated_sharpe(sr, n_obs, n_trials, skew=0.0, kurt=3.0, sr_bench_var=None): """DSR de Bailey & López de Prado. Ajusta por multiple testing.""" e = 0.5772156649 v = sr_bench_var if sr_bench_var is not None else 1.0 / n_obs sr0 = np.sqrt(v) * ((1 - e) * norm.ppf(1 - 1/n_trials) + e * norm.ppf(1 - 1/(n_trials*np.e))) num = (sr - sr0) * np.sqrt(n_obs - 1) den = np.sqrt(1 - skew*sr + ((kurt - 1)/4) * sr**2) return norm.cdf(num / den) ``` **El gate que toda estrategia debe pasar antes de ver dinero real:** 1. **Walk-forward anclado** con reentrenamiento periódico — no un único split. 2. **CPCV** (Combinatorial Purged CV) → distribución de Sharpes OOS, no un punto. 3. **DSR > 0.95** usando el número **honesto** de configuraciones que probaste (sí, incluyendo las que descartaste mentalmente). 4. **PBO < 0.5** (Probability of Backtest Overfitting). 5. **Monte Carlo de bloques** sobre los retornos de trades → percentil 5 del max drawdown. Dimensiona para *ese* drawdown, no para el histórico. 6. **Sensibilidad de parámetros**: la superficie de PnL debe ser una meseta, no un pico. Si mover un parámetro un 10 % te mata, es overfit. 7. **Robustez cross-sectional**: funciona en ≥ 60 % de los símbolos del universo, no solo en BTC. 8. **Atribución**: regresión del PnL contra factores (mercado, momentum, carry, vol). Si tu alpha es solo beta apalancada, lo sabes ahora. --- ## 8. Portfolio y riesgo ```python # src/quantlab/portfolio/sizing.py def vol_target(weights, cov, target_ann_vol=0.15, max_leverage=2.0): import numpy as np w = np.array(list(weights.values())) port_vol = np.sqrt(w @ cov @ w) * np.sqrt(365*24*60) # barras 1m → anual scale = min(target_ann_vol / max(port_vol, 1e-9), max_leverage / max(np.abs(w).sum(), 1e-9)) return {k: v * scale for k, v in weights.items()} ``` Capas de riesgo **en el motor, no en la estrategia** (para que apliquen igual en backtest y en live): - Límite por posición, por sector/cluster de correlación, gross y net. - **Kill switch**: drawdown diario > X % → flat + alerta + bloqueo hasta reset manual. - Circuit breaker de datos: si no llega tick en > N segundos → flat. - Límite de turnover diario (detecta bucles de órdenes). - Fracción de Kelly ≤ 0.25. Siempre. --- ## 9. Ejecución ### 9.1 OMS idempotente (lo más importante del bot) ```python # src/quantlab/execution/oms.py import hashlib from quantlab.core.types import Order def client_order_id(strategy: str, symbol: str, bar_ts: int, seq: int) -> str: raw = f"{strategy}|{symbol}|{bar_ts}|{seq}" return "ql" + hashlib.sha1(raw.encode()).hexdigest()[:20] def reconcile_to_target(target_w, positions, equity, prices, min_notional, tol_bps=15): orders = [] for sym, w in target_w.items(): tgt_qty = w * equity / prices[sym] delta = tgt_qty - positions.get(sym, 0.0) notional = abs(delta) * prices[sym] if notional < min_notional: # no tocar ruido continue if abs(w - positions.get(sym,0.0)*prices[sym]/equity) * 1e4 < tol_bps: continue # banda muerta: ahorra fees orders.append(Order(symbol=sym, qty=delta, side="buy" if delta>0 else "sell")) return orders ``` Claves: - **`clientOrderId` determinista** → si reenvías por timeout, el exchange rechaza el duplicado. Esto evita el desastre clásico de doble posición. - **Banda muerta** (`tol_bps`) → sin esto, el rebalanceo continuo te come vivo en comisiones. - **Reconciliación al arrancar**: consulta posiciones y órdenes abiertas reales, compáralas con el estado local, y si difieren → alerta y no operes hasta resolver. ### 9.2 Adaptadores Una interfaz, tres implementaciones: ```python class Broker(Protocol): def positions(self) -> dict[str, float]: ... def equity(self) -> float: ... def submit(self, order: Order) -> str: ... def cancel_all(self, symbol: str | None = None) -> None: ... ``` - `PaperBroker` — simula contra el feed live real. Es tu primer destino. - `BinanceTestnetBroker` — testnet de futuros, gratis, con API idéntica. - `BinanceBroker` — producción. Mismo código, otra URL y otras keys. ### 9.3 El runner ```python # src/quantlab/live/runner.py import structlog, time log = structlog.get_logger() def run(strategy, broker, feed, risk, state, alerts, heartbeat): state.reconcile(broker) # 1. arrancar en estado conocido for bar in feed: # 2. bloquea hasta cierre de barra try: if feed.staleness() > 90: risk.flatten(broker, "stale_data"); alerts.critical("Feed stale"); continue target = strategy.on_bar(feed.context(bar.ts)) target = risk.apply(target, broker.equity(), state) # 3. riesgo SIEMPRE después orders = reconcile_to_target(target, broker.positions(), broker.equity(), feed.prices(), ...) for o in orders: oid = broker.submit(o) state.record_order(o, oid, bar.ts) # 4. persistir ANTES de seguir state.snapshot(bar.ts, target, broker.positions(), broker.equity()) heartbeat.ping() # 5. dead man's switch except Exception as e: log.exception("bar_failed", ts=bar.ts) alerts.critical(f"Error: {e}") risk.flatten(broker, "exception") raise # fail fast, que systemd reinicie ``` Estado en SQLite (`orders`, `fills`, `snapshots`, `pnl`). Nunca en memoria. Nunca en un diccionario de Python. --- ## 10. Infraestructura live, 0 € ### 10.1 El VPS **Oracle Cloud Always Free**: VM ARM Ampere con 4 vCPU y 24 GB RAM, gratis permanentemente. Es, con diferencia, la mejor oferta gratuita que existe. Alternativa: Google Cloud e2-micro o Fly.io free tier. ```bash # Hardening mínimo ufw default deny incoming && ufw allow 22/tcp && ufw enable # SSH solo con clave, sin root, fail2ban # Reloj: chrony con servidores del exchange — la deriva te genera órdenes rechazadas timedatectl set-ntp true ``` ### 10.2 Docker ```dockerfile # docker/Dockerfile FROM python:3.12-slim RUN pip install --no-cache-dir uv WORKDIR /app COPY pyproject.toml ./ RUN uv pip install --system -e . COPY src/ src/ COPY conf/ conf/ ENV PYTHONUNBUFFERED=1 TZ=UTC ENTRYPOINT ["ql"] ``` ```yaml # docker/compose.yml services: bot: build: {context: .., dockerfile: docker/Dockerfile} command: ["live", "--config", "conf/live/prod.yaml", "--mode", "paper"] env_file: [.env] volumes: ["../data:/app/data", "../state:/app/state"] restart: unless-stopped logging: {driver: json-file, options: {max-size: "50m", max-file: "5"}} prometheus: image: prom/prometheus volumes: ["./prometheus.yml:/etc/prometheus/prometheus.yml"] grafana: image: grafana/grafana ports: ["127.0.0.1:3000:3000"] ``` Grafana lo expones con **Cloudflare Tunnel** (gratis) en vez de abrir puertos. ### 10.3 Alertas y dead man's switch ```python # src/quantlab/live/alerts.py import httpx, os class Telegram: def __init__(self): self.t = os.environ["TG_TOKEN"]; self.c = os.environ["TG_CHAT"] def send(self, msg: str): httpx.post(f"https://api.telegram.org/bot{self.t}/sendMessage", json={"chat_id": self.c, "text": msg}, timeout=10) class Heartbeat: # healthchecks.io — gratis def __init__(self, url): self.url = url def ping(self): httpx.get(self.url, timeout=5) ``` El heartbeat es **no negociable**: si el bot muere a las 3 AM y no te enteras, da igual lo buena que sea la estrategia. healthchecks.io te avisa cuando *deja* de recibir pings — detecta exactamente el fallo que el propio bot no puede reportar. Métricas a Prometheus: equity, posiciones, latencia de orden, tasa de rechazo, slippage realizado vs modelado, staleness del feed, deriva del reloj. ### 10.4 Secretos Nunca en el repo. Dos opciones gratuitas: - `.env` en el VPS con permisos `600`, fuera de git. - **SOPS + age**: cifras `conf/live/secrets.enc.yaml` y *sí* lo commiteas; la clave privada vive solo en el VPS. API keys del exchange: **sin permiso de retirada**, con whitelist de IP, y una key separada de solo lectura para el dashboard. --- ## 11. Plan de ejecución: 8 semanas | Semana | Entregable | Criterio de "hecho" | |---|---|---| | **1** | Scaffolding + CI verde + `ql ingest` funcionando | 3 años de klines 1m de 20 símbolos en el lago, informe de calidad limpio | | **2** | Catálogo DuckDB + features + Context blindado | Test que demuestra que `Context` no puede ver el futuro | | **3** | Motor de backtest + modelo de costes + métricas | Golden test congelado; reproduce un benchmark conocido (buy&hold BTC) al céntimo | | **4** | Módulo de validación (CPCV, DSR, PBO, MC) | Pasas una estrategia aleatoria por el gate → la rechaza | | **5** | Primera estrategia real (momentum cross-sectional o carry de funding) | Pasa los 8 criterios del gate | | **6** | OMS + PaperBroker + runner + estado SQLite | Test de paridad research↔live < 1e-6 | | **7** | Deploy en Oracle + Grafana + Telegram + heartbeat | 7 días en paper sin intervención manual | | **8** | Testnet real → micro-capital | 2 semanas testnet, luego **capital que puedas perder entero** | > Semana 5 es donde la gente se atasca y empieza a inventar. Si la primera estrategia no pasa el gate, **no relajes el gate**: cambia de estrategia. El gate es el activo más valioso del repositorio, no la estrategia. --- ## 12. Checklist de "NO despliegas si..." - [ ] No existe test de paridad research↔live - [ ] El `clientOrderId` no es determinista - [ ] No hay reconciliación de posiciones al arrancar - [ ] No hay kill switch por drawdown, en el motor (no en la estrategia) - [ ] No hay heartbeat externo - [ ] El DSR se calculó con un `n_trials` deshonesto - [ ] No hay golden tests del backtester - [ ] La estrategia muere con costes 3× - [ ] El PnL depende de < 5 % de los trades (concentración) - [ ] La API key tiene permiso de retirada - [ ] Los secretos están en git - [ ] No sabes cuál es tu máximo drawdown al percentil 5 por Monte Carlo --- ## Dónde invertir el esfuerzo (la parte contraintuitiva) El reparto honesto de valor en un quant lab: - **40 % datos** — calidad, PIT, validación. Es aburrido y es donde está casi todo el alpha perdido. - **30 % validación** — el gate estadístico. Lo que te impide perder dinero con tu propia creatividad. - **20 % ejecución** — idempotencia, reconciliación, costes. Lo que convierte un backtest en PnL. - **10 % estrategia** — sí, solo el 10 %. Las ideas son baratas; la infraestructura que te dice cuáles son falsas no lo es. Casi todo el mundo invierte el 90 % en el último 10 %. Esa es la razón principal por la que la mayoría de laboratorios personales no producen nada aprovechable, y esa es exactamente la ventaja que te da hacerlo al revés. Si quieres, te desarrollo en detalle cualquier módulo concreto: el motor de backtest completo, el `Context` blindado, el OMS con manejo de fills parciales, o la primera estrategia con su gate de validación entero.

QUANT LAB