Initial commit: Arbitrage

odds/README.md

@@ -0,0 +1,49 @@
+# Odds module
+
+Handles **ingestion and storage** of sports odds from [The Odds API](https://the-odds-api.com/). Arbitrage logic will consume normalized odds from this layer once implemented.
+
+## Contents
+
+| Path | Description |
+|------|-------------|
+| `data/samples/boxing_odds.json` | Snapshot of boxing `h2h` odds (~1 MB) |
+| `scripts/fetch_odds.py` | CLI to pull live odds and save JSON |
+
+Legacy path `api-pull/Odds/boxing_odds.json` may still exist locally; prefer `data/samples/` for new work.
+
+## Fetching odds
+
+```bash
+# From repository root, with ODDS_API_KEY set
+python odds/scripts/fetch_odds.py \
+  --sport boxing_boxing \
+  --regions uk,eu \
+  --markets h2h \
+  --out odds/data/samples/boxing_odds.json
+```
+
+### Script functions
+
+| Function | Purpose |
+|----------|---------|
+| `get_api_key()` | Reads `ODDS_API_KEY` from the environment |
+| `fetch_odds(sport, regions, markets, api_key)` | HTTP GET to `/v4/sports/{sport}/odds` |
+| `save_odds(data, output_path)` | Writes pretty-printed JSON |
+| `main()` | Parses CLI args and runs fetch + save |
+
+## Sample data
+
+`boxing_odds.json` is an array of **events**. Each event has `home_team`, `away_team`, `commence_time`, and a `bookmakers` list. Each bookmaker exposes `markets` (e.g. `h2h` head-to-head) with `outcomes` and decimal `price` values.
+
+See [docs/DATA_SCHEMA.md](../docs/DATA_SCHEMA.md) for the full field reference.
+
+## Next steps (arbitrage)
+
+Planned pipeline:
+
+1. **Normalize** — flatten bookmaker/outcome rows per event
+2. **Implied probability** — `1 / decimal_odds` per outcome
+3. **Cross-book compare** — find outcomes where sum of best inverse odds < 1 (arb margin)
+4. **Stake split** — optional Kelly / equal-profit calculators
+
+None of steps 2–4 exist in code yet; this folder is ingestion-only today.