feat(options-gps): market line shopping — multi-exchange divergence comparison

tools/options-gps/README.md

@@ -28,6 +28,41 @@ Turn a trader's view into one clear options decision. Inputs: **symbol**, **mark
 7. **Guardrails:** Filters no-trade when fusion is countermove/unclear with directional view, volatility exceeds threshold (directional views), confidence is too low, or vol bias is neutral (vol view — no exploitable divergence between Synth and market IV).
 8. **Risk Management:** Each strategy type has a specific risk plan (invalidation trigger, adjustment/reroute rule, review schedule). Short straddle/strangle are labeled "unlimited risk" with hard stops at 2x credit loss; they are risk-gated (high-only for short straddle, medium+ for short strangle).
 
+## Market Line Shopping
+
+Compares Synth's theoretical option prices against real exchange prices to identify divergence and exploitable edges — like a sports bettor "shopping for lines."
+
+### Three modes of operation
+
+- **LIVE** — when exchange API keys are present, fetches real-time mark prices from Aevo and Deribit public REST APIs.
+- **PARTIAL** — some live providers succeeded, some fell back to mock.
+- **MOCK** — no API keys configured; uses mock providers with realistic exchange-specific biases. Safe for contributors and CI.
+
+### Edge detection (alpha over agreement)
+
+Alpha is found in *disagreement*, not consensus. When Synth's price diverges from the market mean, it signals a potential exploitable edge. This is quantified statistically:
+
+- **Z-score:** `z = (synth_price - market_mean) / market_stddev` per strike.
+- **Edge score:** Average |z| across all strikes. Higher = more alpha.
+- **Confidence adjustment:** Strong edge (z≥2σ) boosts confidence +0.10; moderate (z≥1σ) +0.06; mild (z≥0.5σ) +0.03; no edge (<0.5σ) reduces −0.02.
+
+### Best execution venue
+
+After strategy selection, identifies which exchange offers the best execution price per leg:
+- **BUY legs:** lowest exchange price wins.
+- **SELL legs:** highest exchange price wins.
+- Displayed on Screen 2 with savings vs Synth price and per-exchange comparison.
+
+### Exchange configuration
+
+```
+AEVO_API_KEY=...
+DERIBIT_CLIENT_ID=...
+DERIBIT_CLIENT_SECRET=...
+```
+
+When these are unset, Options GPS uses mock providers. When set, `LiveDeribitProvider` calls `public/get_book_summary_by_currency` and `LiveAevoProvider` calls `GET /markets` to fetch real-time option mark prices.
+
 ## Synth API usage
 
 - **`get_prediction_percentiles(asset, horizon)`** — 1h and 24h probabilistic price forecasts; used for fusion state and for payoff/EV (outcome distribution at expiry).
@@ -51,4 +86,4 @@ Prompts: symbol (default BTC), view (bullish/bearish/neutral/vol), risk (low/med
 
 From repo root: `python -m pytest tools/options-gps/tests/ -v`. No API key required (mock data).
 
-Test coverage includes: forecast fusion, strategy generation (all views including vol), PnL calculations for all strategy types, CDF-weighted PoP/EV, ranking with vol bias, vol-specific guardrails, IV estimation, vol comparison, risk plans, hard filters, and end-to-end scripted tests.
+Test coverage includes: forecast fusion, strategy generation (all views including vol), PnL calculations for all strategy types, CDF-weighted PoP/EV, ranking with vol bias, vol-specific guardrails, IV estimation, vol comparison, risk plans, hard filters, multi-exchange divergence computation, mock provider behavior, consensus classification, confidence adjustment for divergence, and end-to-end scripted tests.