arbitrage-api/odds/README.md

Odds module

Handles ingestion and storage of sports odds from The Odds API. 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

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