# 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.