spb/crypto-trade-bot

1# crypto-trade-bot — Kraken quantitative trading platform23Self-hosted research, backtesting, paper-trading and (gated) execution platform for Kraken Spot.4**Mode is `offline` by default. No live order can be sent unless a trade key is configured, preflight passes, the5feature flag is on and the owner activates live mode in the UI with a second confirmation (Phase 5, not shipped).**67```8apps/api     Python 3.12 · FastAPI · asyncpg · Redis · numpy/pandas/scipy/statsmodels   (package `ktrade`)9apps/web     Next.js · TypeScript · Tailwind v4 · TanStack Query · lightweight-charts10migrations   plain SQL, applied by `ktrade migrate` (Timescale hypertables if the extension exists)11docs         ARCHITECTURE · THREAT-MODEL · RUNBOOK · KRAKEN-API-NOTES · RESEARCH-REPORTS12deploy       Prometheus / Grafana provisioning13```1415## Quick start (local, Apple Silicon)1617```bash18cp .env.example .env                      # then set KTRADE_SECRET_KEY and KTRADE_OWNER_PASSWORD_HASH19docker compose up -d db redis             # or use Homebrew postgresql@17 + redis20make setup                                # uv venv + pip install, pnpm install21make migrate && make backfill             # schema + first OHLC pull (≤720 bars per pair/interval)22make worker &                             # pair discovery, OHLC accumulation, WebSocket v2 stream23make api &                                # http://127.0.0.1:8470/api/docs24make web                                  # http://localhost:8471  (login with the owner password)25make test lint typecheck26```2728Owner password: `cd apps/api && .venv/bin/ktrade set-owner-password` prints a bcrypt hash → `KTRADE_OWNER_PASSWORD_HASH`.2930## What works today (Phase 1 + Phase 2)3132- Kraken REST client with the documented signature (test vector in `tests/test_kraken_signing.py`), monotonic33  nonce, tiered call counter, retries; WebSocket v2 client (ticker/book/trade/ohlc) with CRC32 **book checksum34  verification** and automatic resubscription on mismatch; reconnect with backoff; heartbeat watchdog.35- Pair metadata discovery (ordermin/costmin/tick/lot decimals/status/leverage) — capabilities are read from the36  exchange, never hard-coded. `XBT`→`BTC` naming normalised to WS v2 symbols.37- Postgres schema: candles (open-time keyed, `closed` flag), trades, latest ticker/book, 1-s microstructure38  samples, data gaps, backtest runs, hash-chained **immutable audit log**, risk state, paper ledger tables.39- Event-driven backtester: decisions at bar close, execution at next open (+ optional latency), maker/taker40  fees, spread, slippage, square-root impact, participation-capped **partial fills**, lot rounding, exchange41  minimums, independent **risk gateway** on every order. Proven no-lookahead by tests.42- Strategy SDK + plugins: time-series momentum (vol-targeted), MA ensemble, z-score mean reversion with OU43  half-life + regime filter + cost-aware entries; benchmarks buy&hold / cash / simple momentum / equal-risk.44- Validation: holdout, anchored/rolling walk-forward with embargo, parameter sensitivity maps, block-bootstrap45  CIs, deflated Sharpe, stress scenarios (fees ×2, spread ×3, slippage, latency, liquidity collapse, outage46  gap), shuffled-trade Monte Carlo. Full provenance (commit, dataset hash, params, seed, window, costs).47- Web terminal: overview, market explorer (live candles/book/tape), strategy lab, backtest explorer + compare,48  risk center (limits, kill switch, what-if evaluator, audit), reports, settings (credential status, preflight).49- Observability: structured JSON logs with correlation ids, Prometheus metrics at `/api/metrics`, health endpoint.5051## Known limitations (honest list)5253- Kraken REST OHLC returns at most 720 bars per pair/interval; history **accumulates from first deployment**54  (1-min: 12 h, 1-h: 30 days, 1-d: ~2 years at first pull). Long backtests on fine intervals need a licensed55  external dataset (not included). Results on short windows are statistically weak — the UI says so.56- Phases 3–5 are not implemented: cointegration/Kalman, GARCH/HMM regimes, portfolio optimisation,57  market-making simulation, paper execution loop, live adapter. Pages exist as clearly-labelled placeholders.58- WS v2 allows one OHLC interval per symbol per connection → only 1-min bars are streamed; other intervals come59  from REST polling (≤ 60 s lag).60- Kraken has no Spot sandbox; the only dry-run is `AddOrder validate=true` (used by preflight).61- No shorting / margin: strategies are long-only spot.62- Timescale is optional; without the extension plain B-tree indexes are used (fine at this scale).6364See `docs/RUNBOOK.md` for operations and `docs/THREAT-MODEL.md` for security assumptions.65