50 lines
1.8 KiB
Markdown
50 lines
1.8 KiB
Markdown
|
# 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.
|