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