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 only today: moneyline / spread / total (`h2h`, `spreads`, `totals`).
- 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: betmgm, betonline, betrivers, draftkings, fanduel, novig. 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. Player props / team totals / periods are cataloged as planned, not queryable on /odds.
- 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. betmgm, betonline, betrivers, draftkings, fanduel, novig |
| markets | no | queryable only: h2h, spreads, totals |
| event_id | no | single event |
| commence_after | no | ISO-8601 |
| commence_before | no | ISO-8601 |

Available market aliases: h2h→moneyline, spreads→spread, totals→total
Planned player props (not on /odds): 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_hits, player_shots, player_anytime_td

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)

## 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.
8. Fetch OpenAPI when generating clients.
9. Do not assume Fresh has newer odds than Standard — same snapshot, higher poll allowance only.

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