Updown

CLI-only Python research system for Polymarket crypto Up/Down markets. It downloads bounded public datasets, builds research datasets, trains/evaluates separate outcome, asset-price, and smart-money/trader models, and runs paper/demo simulations only.

This project has no UI, no dashboard, no wallet/private-key logic, no live order placement, and no real copy trading.

See docs/DEEP_DIVE.md for the full system guide (data sources, blockers, NO TRADE reasons), docs/PROJECT.md for command reference, and docs/LIVE_DEEP_DIVE.md for live-terminal gates.

Setup

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Linux/macOS:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Every command below should be run from the activated virtual environment.

Core CLI

updown data download
updown data inspect
updown data audit
updown data align-report

updown status
updown next
updown models --limit 12
updown discover --asset BTC --duration 5m
updown check BTC 5m
updown live BTC 5m
updown live ETH 5m
updown live SOL 5m
updown live XRP 5m
updown live BTC 15m
updown live --all
updown models
updown demo BTC 5m --stake 1

updown traders leaderboard --period daily --sort profit --limit 20 --save
updown traders discover
updown traders profile --wallet ADDRESS
updown traders watch
updown traders analyze
updown traders reconstruct --wallet ADDRESS --market MARKET_ID
updown traders build-dataset
updown traders audit
updown traders evaluate
updown traders backtest-copy

updown build price-dataset
updown build outcome-dataset

updown improve BTC 5m --seconds 300
updown train outcome
updown train outcome --include-trader-features
updown train price --target return_to_market_end
updown train price --target price_at_market_end --asset BTC
updown train all

updown evaluate outcome
updown evaluate price --compare-persistence
updown evaluate price-vs-outcome
updown evaluate ablation
updown evaluate walk-forward

updown backtest
updown compare

updown smoke build
updown smoke train
updown smoke backtest
updown smoke predict

Research Boundaries

Outcome models predict p_up, the probability a market resolves Up. Price models default to normalized returns/direction; raw price-at-market-end training is asset-specific only. Trader models analyze public smart-money/whale signals and whether they improve model performance.

These labels and model families are kept separate. Trader behavior is never trusted blindly; it must pass relevance, sample-size, latency, liquidity, and backtest checks.

Data Quality And Leakage

Empty datasets fail loudly with clean CLI panels by default; pass --debug before the command to see a full traceback. Dataset rows include quality tiers, validity flags, and invalid_reason fields. Outcome training and realistic backtests require real Polymarket markets, real CLOB books, real thresholds, and real labels. Synthetic/exchange fallback rows are smoke-test or price-development rows only.

The normal live workflow is:

updown status
updown check BTC 5m
updown live BTC 5m
updown demo BTC 5m --stake 1

updown live is real-only by default. It does not use exchange-only fallback unless --allow-fallback is passed, and fallback mode is labeled as not real Polymarket data.

Live mode syncs the selected recurring Polymarket slug against Gamma and Polymarket's website crypto price route before the first tick. For active crypto Up/Down markets, Price To Beat comes from the website route's openPrice. CLOB REST provides the full book/depth, and the market websocket is used for realtime top-of-book updates when available.

The live terminal now separates current direction, model forecast direction, and value edge. The Decision Detail panel shows BUY/SELL/HOLD/NO TRADE candidates with pass/block/fail reasons, and counter-forecast buys are blocked by default.

To improve models with newly collected data, run:

updown improve BTC 5m --seconds 300

This collects a fresh real CLOB slice, tries to collect recent resolutions, rebuilds datasets, retrains price models, and reports whether trusted outcome training is ready.

Completed live windows are folded back into price training as real_clob_price rows when the bot has a near-close spot price. Outcome models remain disabled for live use until real resolution labels exist.

Recommended full loop:

updown status
updown check BTC 5m
updown live BTC 5m --seconds 60
updown improve BTC 5m --seconds 300
updown models --limit 12
updown evaluate price --compare-persistence
updown live BTC 5m