# Execution Prompt: BTC Polymarket 5- and 15-Minute Settlement Prediction Research

## Mission

Build a reproducible, research-only system that estimates the probability that a BTC Up/Down Polymarket contract settles **Up** for both five-minute and fifteen-minute windows. Gather permitted public data, create settlement-aligned labels, train and tune three ML technologies, backtest them with realistic executable costs, and replay every decision from immutable inputs.

**Operating declaration — hyperaggressive edge research, smart risk management:** Search every permitted, decision-time signal and evaluate it rapidly and exhaustively. Pursue only statistically supported, executable mispricing. Be hyperaggressive in data coverage, ablation, replay, monitoring, and rejection of weak hypotheses; be conservative in uncertainty treatment, correlated exposure, liquidity assumptions, and loss containment. A strong model score never overrides a hard risk gate.

The output is a complete research package: raw-data provenance, code, deterministic replays, ablations, statistical and economic evaluation, and a publication-quality report. It is not a live-trading system and it must not place, sign, cancel, or modify any order.

## Non-goals

- Do not trade, create wallets, sign transactions, request trading credentials, or implement order placement.
- Do not claim profitability, alpha, or production readiness from a backtest alone.
- Do not substitute Binance, Coinbase, or another exchange close for the Polymarket settlement source.
- Do not use a future observation, future book state, future fee schedule, or post-resolution market data in a decision-time feature.
- Do not fabricate unavailable historical Chainlink, Polymarket level-2, exchange, fee, or latency data. Record the limitation and stop the affected experiment.
- Do not overwrite existing user work or alter unrelated product systems.

## Smart risk-management doctrine

Treat all five- and fifteen-minute BTC contracts as correlated exposure to the same underlying BTC risk factor. A sequence of apparent independent opportunities is not permission to multiply risk.

- Use a **lower confidence bound** of calibrated settlement probability, not the raw point estimate, when computing executable edge.
- Use a conservative upper quantile of transaction costs, latency, and slippage, not only their historical means.
- Any sizing research must use a bounded fractional-Kelly-style calculation or an equivalently documented risk budget. The output must be capped by the smallest of: available executable depth, per-contract limit, total correlated BTC exposure limit, per-venue limit, regime limit, and drawdown/circuit-breaker limit.
- Maintain a single aggregate exposure ledger across overlapping 5-minute and 15-minute contracts, Up and Down positions, and all simulated entries. Do not net exposures unless the contract payoff relationship is proven in the ledger.
- Treat feed disagreement, model disagreement, stale data, spread shock, abnormal cancellation activity, and extreme realized volatility as risk-increasing state variables. They must widen the uncertainty haircut or force `NO_TRADE`.
- Define loss limits, rolling drawdown limits, maximum consecutive decision failures, maximum data-quality failures, and a cooldown rule in an immutable configuration before evaluation. A breached limit halts new simulated entries until the configured recovery condition is met.
- Never tune position-sizing, stop, kill-switch, or circuit-breaker values on the outer test period. Evaluate them by stress and sensitivity analysis.

The system's preferred action is not the most frequent action. It is the action with the best conservative, net-of-cost expected value inside the active risk budget; that action is often `NO_TRADE`.

## Repository, branch, and baseline freeze

- Repository: `$REPOSITORY_ROOT`
- Expected branch at start: `design/automl-autorl-cyber-gyms`
- Baseline SHA when this prompt was written: `ccf159c0a42d6455e281ce19938ac35eb4c48d5b`
- The worktree is known to contain unrelated user changes. Preserve them. All new research work belongs under `research/btc_polymarket/`, with this prompt and final reports under `docs/planning/` and `docs/reports/` only.

Before implementation, capture and save:

```bash
git branch --show-current
git rev-parse HEAD
git status --short
git diff --check
```

Write the literal output and a timestamp to `research/btc_polymarket/contracts/baseline.md`. Do not start implementation until the baseline has been recorded.

## Settlement contract: the non-negotiable source of truth

For every Polymarket BTC Up/Down contract, retrieve and archive the market metadata, rules, outcomes, outcome token IDs, event start/end times, resolution source, tick size, fee configuration, and final resolution.

The label is binary and settlement-aligned:

```text
y = 1 (Up)     if Chainlink BTC/USD at contract end >= Chainlink BTC/USD at contract start
y = 0 (Down)   otherwise
```

`No trade` is an action decision, **not** a third settlement label. The models estimate `P(Up | information available at decision time)`; the policy can abstain.

Each record must include:

- contract slug, event ID, condition ID, and Up/Down token IDs;
- start and end timestamps in UTC plus the original local-market representation;
- Chainlink start and end values used for settlement and their retrieval provenance;
- resolution status and official outcome;
- decision timestamp, remaining time, and all source event timestamps;
- a content hash for the frozen raw inputs used by that decision.

If the official Chainlink values necessary to reproduce a historical settlement cannot be collected under authorized access, mark that contract `UNUSABLE_FOR_LABELING`. Do not proxy it with exchange data.

## Source and data contracts

Use official or explicitly licensed sources only. Save original responses or files before parsing, record access time, source URL/API version, parameters, response hash, and license/terms status in a machine-readable manifest.

| Source | Required data | Contract and failure rule |
|---|---|---|
| Polymarket Gamma API | event/market metadata, rules, outcomes, token IDs, resolution status | Use the public event/market endpoints. Persist the raw metadata response for every contract. |
| Polymarket CLOB API/WebSocket | full Up/Down order-book snapshots, price changes, trades, tick size, minimum size | Use public market-data endpoints only. Persist snapshots and deltas with exchange and receive timestamps. If historical level-2 data is unavailable, do not claim historical executable-book realism. |
| Chainlink BTC/USD Data Stream | settlement-relevant start/end observations and live reference observations | This is authoritative for labels and resolution alignment. Retain the exact observed data and retrieval method. |
| BTC spot and perpetual venues | trades, depth, best bid/ask, funding, open interest, liquidations where legally available | Use documented public feeds with venue-specific schemas and recorded exchange timestamps. Include at least two independent venues only when their historical retention and clock quality are proven. |
| Fee and market rules | historical Polymarket fees, exchange maker/taker fees, funding, tick/minimum size, venue rules | Version by effective date. An unknown historical cost blocks net-PnL claims for the affected interval. |

Use UTC internally. Measure clock alignment, duplicate rate, sequence gaps, reconnects, stale intervals, and event-time versus receive-time delay. Store the raw data append-only, partitioned by source and date; derived data must be regenerable from it.

## Required architecture

Implement this in `research/btc_polymarket/` with explicit package boundaries:

```text
research/btc_polymarket/
  contracts/       # rules, source inventory, schemas, data manifests, baseline
  configs/         # immutable experiment and cost configurations
  data_raw/        # gitignored append-only source captures
  data_curated/    # gitignored derived, reproducible datasets
  src/ingestion/   # source adapters, clocks, schema validation
  src/labeling/    # settlement alignment and decision-time dataset construction
  src/features/    # feature computation and feature availability ledger
  src/models/      # CatBoost, encoder, TLOB-or-LiT head, calibration, ensemble
  src/evaluation/  # purged splits, backtest, replay, metrics, ablations
  tests/           # unit, integration, fixture, and replay tests
  reports/         # generated, versioned research results
  notebooks/       # thin, read-only analysis front ends only
```

Keep raw and curated market data out of Git. Commit schemas, manifests, code, small sanitized fixtures, configurations, and generated summary artifacts only.

## Six-agent execution model

Use six agents in parallel after the baseline and source contracts are accepted. Agents may read any in-scope file but may write only to their assigned area. The coordinator resolves dependencies and never overwrites another agent's files.

| Agent | Role | Exclusive write ownership | Dependency |
|---|---|---|---|
| 1 | PM/coordinator | `research/btc_polymarket/contracts/`, `configs/`, final integration checklist | Begins first; freezes acceptance criteria and source availability. |
| 2 | Data/contracts engineer | `src/ingestion/`, source schemas, sanitized fixtures | Needs Agent 1 source contract. |
| 3 | Label/feature scientist | `src/labeling/`, `src/features/` | Needs frozen source schemas from Agent 2. |
| 4 | ML researcher | `src/models/`, model configs | Needs a versioned dataset contract from Agent 3. |
| 5 | Backtest/replay engineer | `src/evaluation/`, `tests/` for evaluation and replay | Needs decision-time schema from Agents 2–4. |
| 6 | QA/red-team/reporting owner | `reports/`, `docs/reports/`, independent audit evidence | Starts with baseline review; runs independent audit after integration. |

## Research design

### Decision times and horizons

Study both five- and fifteen-minute contracts as separate experiments. Define a pre-registered decision-time grid for each horizon; it must include early, middle, and late-window decisions while excluding an explicit final latency-danger interval. The grid, embargo duration, minimum liquidity, maximum data staleness, maximum position size, correlated-exposure cap, drawdown/circuit-breaker rules, uncertainty haircut, and fee assumptions must be config values frozen before model selection.

Train and report models separately by horizon unless a multi-task design proves an out-of-sample advantage. Never mix a 5-minute target and a 15-minute target without a task identifier and a leakage audit.

### Features

Compute every feature using only data whose event time and receipt time are both admissible at the decision timestamp. Maintain a feature-availability ledger showing its source, lookback, maximum tolerated delay, transformation, and unit.

Candidate feature families:

- Multi-venue BTC mid-price returns, realized volatility, spread, and cross-venue divergence.
- Top-of-book and depth-of-book imbalance, microprice, order-flow imbalance, signed trade flow, cancellation flow, queue depletion, and liquidity slope.
- Perpetual funding, funding change, basis, open-interest change, liquidation activity, and spot-perpetual divergence.
- Polymarket Up and Down executable bid/ask, depth, spread, trade flow, midpoint, implied probability, and time remaining.
- Feed-quality indicators: staleness, sequence gap, clock skew, reconnect state, and disagreement across eligible sources.
- Risk-state indicators: aggregate correlated BTC exposure, contract overlap, depth concentration, realized spread shock, model disagreement, and loss/circuit-breaker state.

No feature may use a response written after the decision time. Encoders, scalers, imputers, normalization statistics, and target encodings must be fitted only on the training fold.

### Required model ladder and ablations

Implement the following as separately addressable experiment configurations.

1. **Market baseline:** executable Polymarket implied probability only.
2. **Transparent baseline:** regularized logistic regression using a minimal, pre-registered feature set.
3. **ML technology A — CatBoost:** calibrated binary settlement classifier on engineered tabular features.
4. **ML technology B — self-supervised LOB encoder:** pretrain a transformer encoder only on raw, unlabelled LOB/trade sequences that are within the training period; output a market-state embedding.
5. **ML technology C — TLOB or LiT directional head:** select one architecture before final testing, document why, and train a supervised binary head using the encoded/current LOB sequence. Do not call TLOB and LiT one model; they are alternatives.
6. **Ensembles:** compare fixed, validation-learned, and calibrated combinations of market baseline, CatBoost, and the deep model.
7. **Optional risk-only regime gate:** HMM or another documented regime detector may block or scale a signal. It is not allowed to alter labels or rewrite a poor predictive result.

Every advanced model must be compared against the market and transparent baselines under identical data, time splits, costs, and opportunity set. If CatBoost or the deep model does not beat the baseline on pre-specified out-of-sample criteria, report that failure plainly.

### Hyperparameter optimization

Use Optuna or an equivalent reproducible optimizer. Hyperparameter selection is allowed only inside the training/validation portion of each outer temporal fold.

- Use nested, purged, embargoed temporal validation. The purge/embargo must cover label horizon, maximum feature lookback contamination, and measured feed-delay uncertainty.
- Freeze the outer holdout period; it may not be opened during tuning, feature selection, architecture selection, calibration, or threshold selection.
- Seed every run and log package versions, accelerator, configuration hash, data-manifest hash, trial history, pruned trials, objective values, and selected parameters.
- Tune forecast quality first (log loss/Brier score/calibration). Tune trade thresholds and any bounded risk-sizing parameter only on validation data and only after a model is frozen.
- Apply the same multiple-testing correction and model-selection audit to all candidates. Do not select based on best backtest PnL alone.

## Event-driven backtest and replay requirements

The evaluator must be event-driven, not bar-close driven. Its clock advances through the captured event stream in timestamp order, exposing only events actually available at that simulated time.

### Execution realism

- Buy Up at the Up ask and buy Down at the Down ask; never fill a buy at midpoint.
- For closing a position, use the relevant bid. Consume visible depth level by level, allow partial fills, and leave unfilled remainder unfilled unless the configured execution rule permits otherwise.
- Apply the fee schedule, tick size, minimum order size, funding where applicable, gas/network cost if applicable, venue-specific slippage, and a conservative latency model. Every cost must be separately reported.
- Model cancel/repost assumptions explicitly. Do not assume queue priority or fills that cannot be supported by captured market data.
- Treat contract payout as $1 for the correct settled outcome and $0 otherwise only after official resolution is known in replay.
- Compute edge using the lower confidence bound of settlement probability and an adverse cost/latency estimate. Produce a `NO_TRADE` decision whenever that conservative executable edge fails after costs and the uncertainty buffer.
- Simulated position size must be zero when any risk gate fails. Otherwise, calculate the proposed size from the frozen bounded-risk rule, then cap it by executable depth and every aggregate exposure, venue, regime, drawdown, and circuit-breaker limit.
- At every replay event, update one correlated-exposure ledger across all open or overlapping BTC contracts. Treat a risk-limit breach as a hard block for new simulated entries; do not allow a new contract to bypass a breached limit.

### Deterministic replay

For every evaluated decision, write an append-only decision record containing raw-input hashes, model/configuration hash, feature vector hash, model probabilities, calibration version, executable book used, cost estimate, gate results, action, simulated fills, and resolution.

`replay --decision-id <id>` must recreate the decision byte-for-byte from frozen inputs. Any mismatch is a test failure and invalidates the associated reported result.

## Metrics and report requirements

Report all outcomes by horizon, time-remaining bucket, liquidity bucket, market regime, venue-availability condition, and train/test period.

### Forecast quality

- Brier score, negative log likelihood, calibration/reliability curve, expected calibration error, ROC-AUC, PR-AUC, and direction accuracy.
- Calibration before and after any calibrator; uncertainty/disagreement distribution; abstention rate.
- Paired comparison with the Polymarket implied-probability baseline and the logistic baseline.

### Economic evaluation

- Gross and net PnL, total fees, slippage, turnover, fill rate, partial-fill rate, realized edge, drawdown, return dispersion, risk-budget utilization, maximum aggregate correlated exposure, circuit-breaker activations, and result sensitivity to latency and fees.
- Report expected value at decision time separately from realized PnL.
- Do not annualize a short, sparse, or overlapping sample without a documented, defensible method. Do not report Sharpe without explaining sampling, overlap, and return aggregation.
- Include zero-cost and realistic-cost results side by side; realistic cost is the only result eligible for a performance claim.

### Required figures and tables

- Data coverage and quality table, including unusable intervals and reasons.
- Settlement-label reproduction audit.
- Train/validation/test timeline with purge and embargo.
- Model ablation table for all seven model configurations.
- Calibration plots and decision-time reliability plots for five and fifteen minutes.
- Net-of-cost equity curve and drawdown, with a clearly labeled paper-replay scope.
- Fee, spread, slippage, latency, and partial-fill sensitivity heatmap.
- Uncertainty-haircut, correlated-exposure, drawdown, and circuit-breaker sensitivity table.
- Error slices: time remaining, market regime, liquidity, and feed quality.
- A one-page “what this does not prove” section.

Label every numeric result as **Measured** only when it was reproduced from retained raw data and a deterministic run; otherwise use **Simulated**, **Illustrative**, or **Design target** as appropriate.

## Acceptance gates

### Gate 0 — baseline freeze

Complete the baseline artifact before writing research code.

### Gate 1 — source, legal, and data availability contract

Document authoritative settlement semantics; source permissions; historic retention; expected fields; fee history; clock strategy; and exact failure handling. GO only if enough authoritative data exists to label and replay the stated experiment.

### Gate 2 — implementation

Implement ingestion, label reconstruction, feature availability enforcement, models, evaluation, and replay within the assigned ownership boundaries.

### Gate 3 — self-review

Inspect the complete diff and run a leakage review. Check all timestamps, input publication delays, fit/transform boundaries, model-selection boundaries, contract equality semantics, executable pricing, and raw-data hashes.

### Gate 4 — independent OpenAI/Codex red-team audit

Agent 6 must independently inspect the repository state, source contract, data manifest, split implementation, models, cost model, results, and replay evidence. Record model/agent identity, scope, files inspected, commands, and evidence. Report findings as CRITICAL/HIGH/MEDIUM/LOW with exact path references, impact, concrete remediation, and GO/NO-GO.

Blocking examples include: resolution-source mismatch; label leakage; unrecorded historical data; mid-price fills; omitted fees; unavailable decision-time information; tuning on test; unreplayable results; invented metrics; unbounded or unaggregated correlated BTC exposure; a risk gate that can be bypassed by a model score; and a live-trading capability.

### Gate 5 — fix findings

Fix all CRITICAL and HIGH findings. Resolve each MEDIUM item by a fix, a tracked follow-up, or explicit user risk acceptance. Re-run affected data, tests, and reports after every material fix set.

### Gate 6 — second independent OpenAI/Codex validation

Run a fresh validation that receives the prior CRITICAL/HIGH findings, the updated diff, and new evidence. It must mark each prior item fixed, downgraded with evidence, or still open. Do not claim a pass otherwise.

### Gate 7 — evidence validation

At minimum run:

```bash
git diff --check
pytest research/btc_polymarket/tests -q
python -m research.btc_polymarket.src.evaluation.validate_manifests
python -m research.btc_polymarket.src.evaluation.validate_no_lookahead
python -m research.btc_polymarket.src.evaluation.replay --verify-sample
python -m research.btc_polymarket.src.evaluation.build_report --verify
```

Replace commands only if the implemented package documents equivalent commands with the same checks. Save actual outputs in the report evidence bundle.

### Gate 8 — final GO/NO-GO

Publish a final report under `docs/reports/` with:

- scope, source period, data availability, and explicit exclusions;
- changed files and reproducible commands;
- model configurations, tuning protocol, and final chosen models;
- forecast and economic results with all costs;
- red-team findings and second-pass validation status;
- unresolved MEDIUM/LOW issues and residual risk;
- GO/NO-GO for **research and paper replay only**;
- an explicit statement that live execution is out of scope and not authorized.

## Automatic stop conditions

Stop the affected path and issue NO-GO if any of the following occurs:

- Historic labels cannot be reconstructed from the named Chainlink settlement source.
- Required historic Polymarket book data is missing but the evaluation would claim realistic fills.
- Fee, spread, or latency data is unknown for a period used in a net-performance claim.
- Any data source violates its terms, requires unapproved credentials, or has ambiguous redistribution rights.
- Tests reveal temporal leakage, test-set tuning, timestamp ambiguity, or non-deterministic replay.
- A result relies on point-estimate sizing without an uncertainty haircut, treats overlapping contracts as independent, omits aggregate exposure from replay, or allows a breached circuit breaker to open new simulated positions.
- The implementation would execute, sign, or transmit a trade.

## Final deliverables

1. Source and settlement-contract ledger.
2. Versioned data manifest with hashes and coverage gaps.
3. Reproducible ingestion, labeling, feature, model, backtest, and replay code.
4. CatBoost, pretrained LOB encoder, and TLOB-or-LiT ablation results for both horizons.
5. Cost-aware, executable-book replay with no-trade decisions.
6. Deterministic decision-level replay evidence.
7. HTML and PDF research report, plus a compact executive summary.
8. OpenAI/Codex red-team report and second validation report.
9. Smart risk-management ledger and stress report showing uncertainty haircuts, correlated exposure, loss limits, circuit-breaker behavior, and all `NO_TRADE` causes.

Do not commit, push, deploy, or enable live trading unless the user explicitly authorizes each action in a later request.