# Polymarket Chainlink Lag Research

This document defines a formal test for the short-horizon hypothesis:

- Binance/Coinbase dislocation filter
- order book imbalance filter
- delayed entry after signal open
- fixed holding horizon

The goal is **falsification first** (is there any robust edge after costs?), not storytelling.

## Required Input Data

Prepare one CSV at `RenTech/data/logs/polymarket_chainlink_ticks.csv` with these columns:

- `ts` (UTC timestamp; parseable by pandas, e.g. `2026-04-21T14:31:05.123Z`)
- `binance_px` (Binance BTC reference price)
- `coinbase_px` (Coinbase BTC reference price)
- `chainlink_px` (oracle/reference price used by market)
- `market_mid` (Polymarket contract midprice you would trade)
- `orderbook_imbalance` (signed imbalance metric; positive means bid pressure)

## Strategy Logic Implemented

Signal event opens when:

- `abs(binance_px - coinbase_px) >= min_spot_delta_usd`
- `abs(orderbook_imbalance) >= min_imbalance_abs`

Direction:

- `long` if `(0.5*(binance_px+coinbase_px) - chainlink_px) > 0`
- `short` otherwise

Consistency filter:

- `long` requires `orderbook_imbalance > 0`
- `short` requires `orderbook_imbalance < 0`

Execution:

- Enter first tick in `[entry_delay_min_sec, entry_delay_max_sec]` after signal open
- Exit at first tick `hold_sec` after entry
- Fee model: `fee_bps_per_side` on entry and exit notionals
- Cooldown prevents overlapping signal opens (`signal_cooldown_sec`)

## Outputs

- Trades CSV: `RenTech/data/logs/polymarket_chainlink_backtest_trades.csv`
- Summary JSON: `RenTech/data/logs/polymarket_chainlink_backtest_summary.json`

## Runbook

1) Collect live data into the required CSV schema:

```bash
cd /Users/robzingale/trading_bot && .venv/bin/python RenTech/data_pipeline/collect_polymarket_chainlink_ticks.py --token-id YOUR_POLYMARKET_TOKEN_ID --out-csv RenTech/data/logs/polymarket_chainlink_ticks.csv --interval-sec 1 --duration-sec 3600 --book-depth-levels 5
```

2) Run the formal backtest with default hypothesis parameters:

```bash
cd /Users/robzingale/trading_bot && .venv/bin/python RenTech/strategy_stack/backtest_polymarket_chainlink_lag.py --input-csv RenTech/data/logs/polymarket_chainlink_ticks.csv --min-spot-delta-usd 50 --min-imbalance-abs 1.8 --entry-delay-min-sec 60 --entry-delay-max-sec 180 --hold-sec 14 --signal-cooldown-sec 300 --fee-bps-per-side 5
```

3) Run a sensitivity pass (tight/loose thresholds and hold times):

```bash
cd /Users/robzingale/trading_bot && .venv/bin/python RenTech/strategy_stack/backtest_polymarket_chainlink_lag.py --input-csv RenTech/data/logs/polymarket_chainlink_ticks.csv --min-spot-delta-usd 25 --min-imbalance-abs 1.5 --entry-delay-min-sec 30 --entry-delay-max-sec 120 --hold-sec 10 --signal-cooldown-sec 180 --fee-bps-per-side 7 --out-trades RenTech/data/logs/polymarket_chainlink_backtest_trades_sensitivity.csv --out-summary RenTech/data/logs/polymarket_chainlink_backtest_summary_sensitivity.json
```

4) Compare both summaries directly:

```bash
cd /Users/robzingale/trading_bot && .venv/bin/python - <<'PY'
import json
from pathlib import Path
base = json.loads(Path("RenTech/data/logs/polymarket_chainlink_backtest_summary.json").read_text())
sens = json.loads(Path("RenTech/data/logs/polymarket_chainlink_backtest_summary_sensitivity.json").read_text())
print("BASE", base["summary"])
print("SENS", sens["summary"])
PY
```