Everything you need to build on Odds Vault

# Odds Vault API — agent handoff

Use this contract when building against Odds Vault **v1**.

## Product boundaries
- Pregame full-game markets today: moneyline / spread / total (`h2h`, `spreads`, `totals`), plus player props (`markets=player_props`, opt-in — see below).
- Responses are private R2 **current** snapshots (rolling per-book refresh; default 60s target, ≤180s source age). Supabase is the control plane only. Requests never scrape books and never fall back to Supabase snapshot tables.
- **Standard and Fresh read the same R2 objects.** Fresh only raises request allowance; it does not buy a separate feed or younger source data.
- **Live books** (customer-visible) are published on the snapshot index and listed by `GET /api/v1/books` / catalog — currently: draftkings, fanduel, betmgm, betrivers, betonline, pinnacle, bovada, mybookie, unibet, pointsbet, novig, betopenly, kalshi, polymarket, prophetx, kutt, betteredge. This set changes without a code deploy when admin promotes/pauses books.
- Account-owned keys from the dashboard only (`ov_live_…`). Entitlement required (`has_paid`, including active trial).
- Rate limits (dual fixed windows, always both): Standard 60/min + 360/hr; Fresh 300/min + 900/hr. Unlimited = no daily/monthly quota.
- Live odds out of scope. Team totals are cataloged as planned, not queryable on /odds.
- Period markets: cataloged as planned, not served via `periods=` — a market SCOPE filter, orthogonal to `markets=`. Accepted values are the canonical period keys (`full`, `1h`, `2h`, `q1`-`q4`, `p1`-`p3`, `i1`, `i1_5`, `f3`, `f7`, `set1`-`set3`) plus `all`; omitting it means `full` only, so existing calls are unaffected either way. `unknown` is never accepted and a market whose period could not be proven is never served.
- Player props: LIVE, opt-in via `markets=player_props` — never in the default `markets=` set, so existing calls are unaffected either way. Covers MLB AND WNBA only today (both in-season; every other tracked sport is out of season or preseason and carries no prop data). There is no per-statistic query filter — request the family and read `identity.statistic` / `identity.subject_id` per market.
- Internal risk scores and quarantined rows are never returned.

## Auth
- Header: `Authorization: Bearer ov_live_<prefix>_<secret>`
- Env var: `ODDSVAULT_API_KEY`
- All routes require a **paid/trial-entitled** account key **except** `GET /api/v1/openapi` (public OpenAPI JSON).
- Signup alone is not enough: subscribe (or start trial) from the dashboard, then mint a key.
- Successful paid responses include six headers: `X-RateLimit-Minute-Limit|Remaining|Reset` and `X-RateLimit-Hour-Limit|Remaining|Reset`.

## Endpoint map
- GET /api/v1/catalog — Full catalog: Sports, books, markets (incl. planned props), product notes, counts.
- GET /api/v1/sports — Sports & leagues: Keys for sport=. Optional group=soccer|basketball|…
- GET /api/v1/books — Sportsbooks: Live books from the R2 index (keys for books=). Soft-empty if index unavailable.
- GET /api/v1/markets — Markets & prop types: status / kind / queryable filters. Planned props included.
- GET /api/v1/status — Freshness status: R2 index board: per-sport fresh/has_snapshot, ages, books. 503 if index missing; ok:false when all stale.
- GET /api/v1/events — Event index: Lightweight board from R2: teams, commence, market/book counts — no quotes.
- GET /api/v1/events/{eventId} — Event detail: Full multi-book markets for one event (R2). include_best=true optional.
- GET /api/v1/odds — Odds snapshot: Full multi-book pregame R2 payload for a sport (+ event_id / commence filters).
- GET /api/v1/convert — Odds convert: American ↔ decimal ↔ implied, or two-way no-vig (home+away).
- GET /api/v1/openapi — OpenAPI 3.1: Machine-readable schema for agents/codegen. No auth required.

OpenAPI (no auth): https://www.oddsvault.app/api/v1/openapi

## Recommended client flow
1. `GET /api/v1/status` — skip sports that are not `fresh`. (503 if the R2 index itself is missing.)
2. `GET /api/v1/catalog` (or /sports, /books, /markets) — populate validators / UI. Prefer live books from API over hardcoded lists.
3. `GET /api/v1/events?sport=` — cheap board for pickers.
4. `GET /api/v1/events/{eventId}?include_best=true` or `GET /api/v1/odds?sport=&event_id=` — full quotes.
5. `GET /api/v1/convert` — American/decimal/implied or two-way no-vig.

## Odds: GET https://www.oddsvault.app/api/v1/odds
| Param | Required | Notes |
| --- | --- | --- |
| sport | yes | nfl, ncaaf, nba, ncaab, wnba, mlb, nhl, mls, epl, la_liga, serie_a, bundesliga, ligue_1, ucl, europa_league, world_cup, soccer_intl, ufc, tennis, boxing |
| books | no | live set e.g. draftkings, fanduel, betmgm, betrivers, betonline, pinnacle, bovada, mybookie, unibet, pointsbet, novig, betopenly, kalshi, polymarket, prophetx, kutt, betteredge |
| markets | no | queryable only: h2h, spreads, totals, player_props |
| event_id | no | single event |
| commence_after | no | ISO-8601 |
| commence_before | no | ISO-8601 |

Available market aliases: h2h→moneyline, spreads→spread, totals→total, player_pass_yds→player_prop, player_pass_tds→player_prop, player_rush_yds→player_prop, player_receiving_yds→player_prop, player_strikeouts→player_prop, player_total_bases→player_prop, player_rbis→player_prop, player_runs→player_prop, player_singles→player_prop, player_doubles→player_prop, player_triples→player_prop, player_hits_runs_rbis→player_prop, player_hits_allowed→player_prop, player_earned_runs→player_prop, player_outs→player_prop, player_home_runs→player_prop, player_stolen_bases→player_prop, player_batter_strikeouts→player_prop, player_hits→player_prop
Player-prop market keys (documentation only — request the whole family with markets=player_props, not these individually): player_pass_yds, player_pass_tds, player_rush_yds, player_receiving_yds, player_receptions, player_points, player_rebounds, player_assists, player_threes, player_strikeouts, player_total_bases, player_rbis, player_runs, player_singles, player_doubles, player_triples, player_hits_runs_rbis, player_hits_allowed, player_earned_runs, player_outs, player_home_runs, player_stolen_bases, player_batter_strikeouts, player_hits, player_shots, player_anytime_td

## Player props (opt-in, family filter only)
- Request with `markets=player_props` (never in the default set — omitting `markets=` never returns props).
- Coverage today: mlb, wnba only. Every other tracked sport is out of season/preseason and carries no prop data even with the family requested.
- Statistics served (sport:statistic(role)): mlb:hits(batter), mlb:total_bases(batter), mlb:rbis(batter), mlb:runs_scored(batter), mlb:home_runs(batter), mlb:singles(batter), mlb:doubles(batter), mlb:stolen_bases(batter), mlb:walks(batter), mlb:hits_runs_rbis(batter), mlb:strikeouts(pitcher), mlb:hits_allowed(pitcher), mlb:earned_runs(pitcher), mlb:outs_recorded(pitcher), mlb:walks_allowed(pitcher), wnba:points(player), wnba:rebounds(player), wnba:assists(player), wnba:three_pointers(player), wnba:points_assists(player), wnba:points_rebounds(player), wnba:points_rebounds_assists(player), wnba:rebounds_assists(player)
- Confusable pairs — the exact traps that silently return a right-looking wrong number if conflated:
- player prop "strikeouts" (statistic: strikeouts) vs batter strikeouts (statistic: batter_strikeouts): MLB only. "strikeouts" bare is always the PITCHER's strikeouts thrown — the higher-volume, more heavily bet market. batter_strikeouts is the HITTER striking out (a bad outcome for that player). They are opposite roles on the same word. No live book currently prices batter_strikeouts distinctly from the pitcher market in production — if one starts, it will appear under batter_strikeouts and must not be read as a substitute for strikeouts, or vice versa.
- hits (statistic: hits) vs hits + runs + RBIs (statistic: hits_runs_rbis): MLB only. hits_runs_rbis is a combo that happens to contain the word "hits" and often shares a numeric line with the plain hits market for the same player — they are still two different products with two different lines to clear. Never substitute one for the other.
- points (statistic: points) vs points + assists (statistic: points_assists): WNBA. A distinct market from points alone, usually priced at a materially higher line. Confusing the two misreads the number a player needs to clear.
- points + assists (statistic: points_assists) / points + rebounds (statistic: points_rebounds) vs points + rebounds + assists (statistic: points_rebounds_assists, "PRA"): WNBA. Three separate combo products at three separate lines for the same player — a two-stat combo's text is a substring of the three-stat combo's conventional abbreviation ("PRA" contains "PA" and "PR"), which is exactly how a naive text match merges them. They never share a market_id.
- Every prop market is two-sided (over/under). Compare quotes only within one `market_id`; `identity.statistic` plus `identity.subject_id` (the player) is what distinguishes one prop from another, the same way `identity.period` distinguishes two totals markets.

Odds headers: `ETag`, `X-Odds-Snapshot-Version`, `X-Odds-Age-Seconds`, plus rate-limit headers. Send `If-None-Match` for 304.

## Events
- `GET /api/v1/events` — summaries with market_count, book_count, books[], market_families[], snapshot_version, age_seconds. Params: sport?, books?, markets?, commence_after?, commence_before?, limit? (default 100, max 500). Response includes limit + max_source_age_seconds.
- `GET /api/v1/events/{eventId}` — full event + optional best_lines. Params: sport?, books?, markets?, include_best=true.

## Status
- `GET /api/v1/status` → ok, refresh_target_seconds, max_source_age_seconds, checked_at, summary (sports_total / sports_with_snapshot / sports_fresh / events_fresh), sports[] with fresh, has_snapshot, version, age_seconds, books[], source_freshness[].
- Valid index with every sport stale → **200** `{ ok: false }`. Missing/invalid index → **503**.

## Convert
- Single: `?american=-110` OR `?decimal=1.91` OR `?implied=0.5238`
- Two-way no-vig: `?home=-110&away=-105` (American)

## Refresh cadence
Every book targets the same default refresh interval — 60s — individually
adjustable per book in the admin panel without a deploy. Catalog books:
draftkings, fanduel, betmgm, betrivers, betonline, pinnacle, bovada, mybookie,
unibet, pointsbet, novig, betopenly, kalshi, polymarket, prophetx. Not every
catalog book is live at a given moment — check `GET /api/v1/books` for the
current live set and each book's actual cadence.

## Errors
400 bad input · 401 auth · 403 subscription_required · 404 event missing · 429 rate limit (minute_rate_limit_exceeded | hourly_rate_limit_exceeded | unauthorized_rate_limit_exceeded) · 503 R2/index/freshness/rate-limit provider

Unauthorized abuse windows: 60/min + 360/hr before generic 401 path.

## Minimal curls
```bash
curl 'https://www.oddsvault.app/api/v1/status' -H 'Authorization: Bearer ov_live_YOUR_KEY'
curl 'https://www.oddsvault.app/api/v1/catalog' -H 'Authorization: Bearer ov_live_YOUR_KEY'
curl 'https://www.oddsvault.app/api/v1/events?sport=nba' -H 'Authorization: Bearer ov_live_YOUR_KEY'
curl 'https://www.oddsvault.app/api/v1/odds?sport=nfl&markets=h2h,spreads,totals&books=draftkings,pinnacle' \
  -H 'Authorization: Bearer ov_live_YOUR_KEY'
curl 'https://www.oddsvault.app/api/v1/convert?american=-110' -H 'Authorization: Bearer ov_live_YOUR_KEY'
curl 'https://www.oddsvault.app/api/v1/openapi'
```

## Implementation checklist
1. Read ODDSVAULT_API_KEY from env (account key from dashboard after entitled subscription/trial).
2. Prefer /status + /catalog + /books over hardcoded sports/books lists.
3. Use /events for boards; /events/{id} or /odds?event_id= for detail.
4. Never send planned market keys to /odds (400).
5. Treat 503 as retry later (missing R2, stale sources, or rate-limit provider). A fresh empty board is 200 with event_count 0.
6. Handle 403 subscription_required by sending the user to checkout/dashboard — not by retrying.
7. Use price_decimal for EV; american for display. price_decimal is derived from price and rounded HALF-UP, so validate it with ROUND_HALF_UP — half-even (Python's round(), NumPy, IEEE-754 default) disagrees on -160 and -800, the only two prices in the feed that land on a two-decimal tie.
8. Fetch OpenAPI when generating clients. Pin info.version and read info.x-changelog to detect contract changes.
9. Do not assume Fresh has newer odds than Standard — same snapshot, higher poll allowance only.
10. Size your consensus from fresh_books (books that actually quote in the payload), not pipeline_fresh_books (scrapers that are merely healthy). The two differ whenever a live book does not price the slate you asked for.
11. Compare quotes only within one market_id, and carry every identity field through your keying — including scale_confidence, which separates a proven sets/games scale from an unproven one, and period_confidence, which separates a market whose period is known from one served as period "unknown" because no period could be proven from the source.

## Sport keys
nfl (NFL), ncaaf (NCAAF), nba (NBA), ncaab (NCAAB), wnba (WNBA), mlb (MLB), nhl (NHL), mls (MLS), epl (Premier League), la_liga (La Liga), serie_a (Serie A), bundesliga (Bundesliga), ligue_1 (Ligue 1), ucl (UEFA Champions League), europa_league (UEFA Europa League), world_cup (FIFA World Cup), soccer_intl (Soccer (other / international)), ufc (UFC), tennis (Tennis (ATP / WTA)), boxing (Boxing)