polymarket-kronos-btc

PAPER-TRADING ONLY. This project never places real orders, never reads private keys, and defaults every external client to read-only. Live execution is intentionally a NotImplementedError stub.

Research and paper-trading system for Polymarket BTC Up/Down 5-minute markets, powered by the Kronos financial time-series foundation model (shiyu-coder/Kronos).

Why this exists

Polymarket runs continuous BTC Up/Down markets that resolve every 5 minutes against the BTC price. A single trader cannot wait passively for resolution — edge changes as new 1-minute candles close inside each window. This project pulls Binance OHLCV data, queries Polymarket Gamma/CLOB for live token prices and market metadata, runs Kronos inference on a short cadence (default 60s) to estimate P(up), and simulates trades when |P(up) − token_price| > threshold. Real-money execution is out of scope.

Quickstart (Arch Linux, Python 3.12 via uv)

cd /home/cola/polymarket
uv sync --extra dev          # creates .venv with Python 3.12 + dev deps
cp .env.example .env         # paper-only defaults; no secrets
make test                    # runs Phase 0 unit tests

Phase status

• Phase 0 (foundation): scaffolding, configs, logging, env validation, risk guards stub, baseline tests. ← current
• Phase 1: Binance 1m + 5m OHLCV fetch.
• Phase 2: Polymarket Gamma + CLOB data layer.
• Phase 3: BTC ↔ Polymarket window alignment + labels.
• Phase 4: Kronos integration (shiyu-coder/Kronos).
• Phase 5: Fine-tune data prep.
• Phase 6: Fine-tune execution scripts.
• Phase 7: Backtest engine (intra-window cadence).
• Phase 8: Paper-trading bot (1m/60s default loop).
• Phase 9: Streamlit / Rich monitoring.
• Phase 10: Risk guards + smoke tests.

Each phase writes a short report at reports/phase_N_summary.md.

Folder map

data/{raw,processed,features,labels}   # all gitignored
models/                                # local model artefacts
checkpoints/                           # fine-tune checkpoints (gitignored)
notebooks/                             # exploratory work
scripts/                               # CLI entry points
src/
  utils/                               # logging, config, env validation
  data/                                # Binance fetcher + alignment
  polymarket/                          # Gamma + CLOB clients (read-only)
  kronos/                              # adapter around KronosPredictor
  backtest/                            # backtest engine
  paper/                               # paper-trading bot
  risk/                                # safety guards (paper-only assert)
  monitoring/                          # Streamlit/Rich dashboard
configs/                               # default.yaml, paper.yaml, backtest.yaml
tests/                                 # pytest suite
reports/                               # per-phase summaries + analysis
logs/                                  # rotating JSONL logs
vendor/                                # Kronos clone (gitignored, P4)

Commands

Command	What it does	Phase
make setup	uv sync --extra dev	P0
make test	Run pytest	P0
make fetch-binance	Pull Binance BTC/USDT 1m + 5m OHLCV	P1
make fetch-polymarket	Pull Polymarket BTC 5m markets + token history	P2
make align	Align BTC bars with Polymarket windows + labels	P3
make prepare-kronos	Build Kronos fine-tune dataset (dry-run validator)	P5
make train-kronos-dryrun	CPU dry run of fine-tune scripts	P6
make train-kronos	GPU fine-tune (no overwrite without backup)	P6
make backtest	Run intra-window backtest	P7
make paper	Start paper bot (60s loop, simulated only)	P8
make monitor	Launch Streamlit dashboard	P9
make kill	Set KILL_SWITCH=1 so paper bot halts next loop	P0
make clean	Remove .venv, __pycache__, build artefacts	P0

Safety

See CLAUDE.md for the full list. Highlights:

• src/risk/guards.py::assert_paper_only() is called at every order-adjacent code path.
• .env is gitignored. .env.example has no secrets.
• CLOB client mode defaults to "read_only"; "live" raises NotImplementedError.
• KILL_SWITCH=1 env stops the paper loop on next tick.

License

Internal research project. Not for distribution.