# Odds-API.io Documentation Index for AI Tools
# This file provides an index of documentation pages for LLMs and AI coding assistants

## Overview
Odds-API.io is a sports betting odds comparison API providing real-time data from 450 bookmakers across 34 sports.

For continuously fresh odds use the WebSocket feed (/guides/websockets); use REST for snapshots and one-off lookups. /odds/updated is a polling fallback: pass the X-Next-Since response header as the next `since`, `markets` is required there. It is a true delta that ships only the market groups that changed since `since`, so merge responses by market name instead of replacing an event.

## Documentation URLs

https://docs.odds-api.io/ - Introduction and overview of the API
https://docs.odds-api.io/quickstart - Get started with your first API call
https://docs.odds-api.io/authentication - API key authentication and security

## Guides

https://docs.odds-api.io/guides/fetching-odds - Fetch and compare odds from multiple bookmakers
Market catalogue: GET /markets?sport=<sport> (no auth required) returns the exact market names, shape, period and prematch/live availability for a sport, use it instead of guessing a name. Every sport parameter in the API takes either spelling, the name or the slug (Ice Hockey or ice-hockey). A listed sport we do not price yet returns an empty markets array, not a 404. Handball ML is always the full-time three-way result (home, draw, away); two-way handball winner prices are under Draw No Bet. Corners lines can include `exactly`; when present, Over and Under both lose on that number
https://docs.odds-api.io/guides/live-events - Live events, match clock and participant logos
https://docs.odds-api.io/guides/value-bets - Prices above a fair-odds estimate, with expected value
https://docs.odds-api.io/guides/arbitrage-bets - Prematch arbitrage opportunities across your bookmakers, margins after exchange fees, stakes within bookmaker limits
https://docs.odds-api.io/guides/dropping-odds - Track significant odds movements from sharp bookmakers
https://docs.odds-api.io/guides/on-sharp - ON Sharp: consensus line from the sharpest books, fixed 2%/2.5% margin, prematch, paid plans (bookmakers=ON Sharp)
https://docs.odds-api.io/guides/websockets - Real-time odds updates via WebSocket
https://docs.odds-api.io/guides/best-practices - Optimize API usage and performance
https://docs.odds-api.io/guides/historical - Historical closing lines for backtesting
Historical data: /historical/closing-lines (bulk, paid: sport + leagues + from/to + markets + bookmakers), /historical/events and /historical/odds (see API reference)
https://docs.odds-api.io/guides/settlement - Bet settlement API: results per event and automatic grading of bets (won, lost, void, half_won, half_lost), 172 markets in 21 sports, paid plans
Settlement: GET /settlements (eventIds, max 50: status pending/live/awaiting_result/settled/cancelled, final flag, scores) and POST /settlements/grade (JSON body, up to 50 selections of eventId + market + side + hdp + label; returns result, reason, final, basis per selection)
https://docs.odds-api.io/guides/sdks - Official TypeScript and Python SDKs
https://docs.odds-api.io/guides/prediction-markets - Prediction market odds (Polymarket, Kalshi)
https://docs.odds-api.io/guides/native-id-mappings - Native id mappings: our selections to a bookmaker's own ids (Polymarket conditionId + CLOB token id, Kalshi contract ticker + yes/no), lookups and bulk sync, paid plans
https://docs.odds-api.io/guides/paying-with-crypto - Pay with BTC, ETH, USDC and more (10+ coins); how crypto renewals are invoiced

## API Reference

https://docs.odds-api.io/api-reference/introduction - API overview and authentication
https://docs.odds-api.io/api-reference/websocket - WebSocket API documentation

## AI Resources

https://docs.odds-api.io/llms-full.txt - Full documentation in a single file (for large context AI tools)
https://docs.odds-api.io/api-reference/openapi.json - OpenAPI specification with complete schemas

## WebSocket Reconnect

- Up to two concurrent WebSocket connections per API key; a third closes the oldest, and a reconnect within 2 seconds of that is refused with close code `1013`, so back off a few seconds
- `permessage-deflate` compression is required on WebSocket connections. Use Node `ws`, a browser, or Python `websockets` (all compress by default); Python `websocket-client` and PHP `textalk/websocket` cannot compress; connections without it are refused with HTTP 426
- Each WebSocket update includes a globally increasing `seq`
- Updates arrive in `seq` order per connection (`seq` never decreases; the same update sent for several bookmakers shares one `seq`, so identify a frame by `id` + `bookie` + `seq`); reconnect with the highest `lastSeq` you received to get a compacted replay of missed updates (`replayComplete=true` adds a `replay_complete` marker when the catch-up is done)
- Replay is latest-state per `eventId:bookie`, not every intermediate tick
- `status=prematch` connections get a sequenced, replayed `no_markets` per bookmaker when an event starts (or is settled/cancelled before starting), closing its pre-match odds (a reconnect that gets neither replay nor pushed state still gets the closes after its `lastSeq`, without seq); a `lastSeq` reconnect with the `status` channel also resends the current `status` of live and recently finished events before `replay_complete`
- Subscribe to channels with `?channels=odds,scores,status` (default `odds` keeps the existing stream); `scores`/`status` add `score`/`status` messages (event-level, best-effort, not replayed). `channels` is an allowlist - you get ONLY the channels you list, so include `odds` to keep receiving odds (`channels=scores,status` stops odds)
- `score` messages carry scores+periods only (no `status` field), sent on every score change; `status` messages are sent once per transition - `pending` (new match added), `live`, `settled`, `cancelled` - and include the current scores
- live `score` and live-`status` messages also include an optional `clock` snapshot (minute, playedSeconds, period, running, statusDetail, serve, injuryTime, periodStartedAt - same shape as `GET /events/live`) to re-anchor a client-side ticker; omitted on pending/settled/cancelled and on sports without a clock. The clock arrives only with an event, so seed the initial value from `GET /events/live` on connect, then let the WebSocket re-anchor it
- WebSocket message types: `welcome`, `created`, `updated`, `deleted`, `no_markets`, `score`, `status`, `resync_required`
- If replay cannot be served safely, the server sends `resync_required`
- Recovery path: fetch `/odds` or `/odds/multi` with `includeSeq=true`, read the `X-OddsAPI-Seq` header, then reconnect with `lastSeq`

## Base URL

https://api.odds-api.io/v3

## Scores & Period Scores

The API provides scores for all periods, not just the final result. The `scores` object contains `home`, `away`, and a `periods` map with the score for each period.

Period keys, the same for every sport and source (top-level `home`/`away` includes overtime but never a penalty shootout):
- `p1`, `p2`, ... `pN` - score in that period only (half / quarter / period / inning / games in a set)
- `ft` - running total at the end of regulation (set sports: sets won)
- `ot` - running total after overtime / extra time / extra innings, regulation included (when played)
- `ap` - running total after a penalty shootout, shootout goals included (when there was one); the shootout alone is `ap` minus `ot` (or `ft`)
- `currentgame` - current game points (live tennis)
- `map1`, `map2`, ... - map winner (esports): `1` for the side that won the map, `0` for the other
- `map1_score`, `map2_score`, ... - score within the map (esports): rounds for Counter-Strike, kills for League of Legends and Dota 2. Optional: added after a series settles, only for maps with a verified score

So football uses `p1`, `p2` + `ft` (+ `ot`, `ap`); ice hockey `p1`-`p3`, `ft` (+ `ot`, `ap`); basketball `p1`-`p4`, `ft` (+ `ot`). Some events also carry the older spellings `period1`-`period5`, `overtime`, `penalties` and `fulltime`, which stop on 12 November 2026, 09:00 UTC; read the keys above.

Example (football):
```json
"scores": { "home": 0, "away": 1, "periods": { "p1": { "home": 0, "away": 0 }, "ft": { "home": 0, "away": 1 } } }
```

Example (ice hockey decided in overtime):
```json
"scores": { "home": 4, "away": 3, "periods": { "p1": { "home": 0, "away": 1 }, "p2": { "home": 2, "away": 1 }, "p3": { "home": 1, "away": 1 }, "ft": { "home": 3, "away": 3 }, "ot": { "home": 4, "away": 3 } } }
```

Example (football decided on penalties):
```json
"scores": { "home": 1, "away": 1, "periods": { "p1": { "home": 0, "away": 1 }, "ft": { "home": 1, "away": 1 }, "ap": { "home": 4, "away": 3 } } }
```

This enables complete settlement of all market types including half-time results and period-specific markets.

## Key Endpoints

GET /sports - List available sports (no auth required)
GET /bookmakers - List available bookmakers with name, active, createdAt and status (status ok/degraded/down, reason maintenance/unavailable); odds from "down" books are not served (no auth required)
GET /leagues?sport={slug}&apiKey={key} - List leagues for a sport
GET /events?sport={slug}&apiKey={key} - List events for a sport. Esports events add an `esports` object: game, parent league, region, format (bestOf/firstTo + games). Defaults to the next 14 days when no `to` is given; pass `to` (RFC3339) to widen. Hard-capped at 5000/response - paginate with limit+skip.
GET /events/live?apiKey={key} - Get currently live events (includes optional clock object: minute, playedSeconds, period, running, statusDetail, serve, injuryTime, and periodStartedAt (unix seconds, wall time) only when there is no played clock). Cricket has no clock; its per-innings detail is in scores.periods.inningN, which adds cricket-only `wickets` and `overs` pairs alongside home/away runs
GET /events/search?query={term}&status={upcoming|live}&apiKey={key} - Search upcoming (default) or live events by team/league name
GET /events/{id}?apiKey={key} - Get event by ID (live events include the clock object)
GET /odds?eventId={id}&bookmakers={list}&apiKey={key}&markets={names} - Get odds for an event
GET /odds/multi?eventIds={ids}&bookmakers={list}&apiKey={key}&markets={names} - Get odds for multiple events (up to 10)
GET /odds/updated?since={timestamp}&bookmaker={name}&sport={name}&apiKey={key}&limit={n}&markets={names} - Get only the market groups that changed since `since` (returns X-Server-Time/X-Next-Since headers for delta polling; bookmaker=Bet365 also returns "Bet365 (no latency)")
GET /odds/summary?eventId={id}&apiKey={key} - Best, average, median, worst and fair price per market line across bookmakers (Growth plans and above)
GET /odds/summary/multi?eventIds={id1,id2}&apiKey={key} - Odds summary for up to 10 events (counts as 1 request)
GET /odds/movements?eventId={id}&bookmaker={name}&market={name}&marketLine={line}&apiKey={key} - Get prematch odds movement history for one market line (names case-insensitive, omit marketLine for the main line or for markets without one). History is recorded only for a fixed set of bookmakers: 10BET, 12bet, 1xbet, 22Bet, 888Sport, BC.Game, Bet365, Betano, Betclic FR, Betfair Exchange, Betfair Sportsbook, Betinia DK, BetMGM, Betsson, BetVictor, Betway, Bovada, Bwin ES, Bwin IT, CloudBet, ComeOn, Coolbet, DanskeSpil, DraftKings, Duel, Eurobet IT, FanDuel, FB Sports, GG.bet, Goldbet IT, Interwetten, Kalshi, Kambi, Ladbrokes, M88, Marathonbet, NetBet, NordicBet, Norsk Tipping, Novibet GR, ON Sharp, Paddy Power, Pamestoixima, Polymarket, Rollbit, Roobet, Sbobet, Sharp Exchange, SingBet, Sisal IT, Snai IT, SportyBet, Stake, Stoiximan, Superbet, Tipico DE, Tipsport.cz, Unibet, Unibet FR, Vbet, Veikkaus, William Hill, Winamax FR, and selected sharp books. Other bookmakers return a 404
GET /value-bets?bookmaker={name}&apiKey={key} - Get prices above a fair-odds estimate (optional: sport={slug}, league={slug} requires sport, includeEventDetails). Rows carry firstSeenAt and bookmakerOddsUpdatedAt (last price write, may be absent); expectedValueUpdatedAt only moves when EV or the sharp limit increases, so it is not a freshness signal
GET /arbitrage-bets?bookmakers={list}&apiKey={key} - Get prematch arbitrage opportunities, best combination per event/market/line (optional: sport={slug}, league={slug} requires sport, markets={names}, minProfit={percent}, allCombinations=true, limit, includeEventDetails). Margins use prices after exchange fees; legs carry netOdds, maxStake and oddsUpdatedAt when known; totalStake can be below 1000 when a limit caps the split
GET /dropping-odds?sport={slug}&league={slug}&leagues={slug,slug}&markets={name,name}&apiKey={key} - Get dropping odds from sharp bookmakers (paid plans only). Use leagues (comma-separated) to filter by multiple leagues at once; mutually exclusive with league. Use markets (comma-separated) to filter by one or more market names.
GET /mappings?bookmaker={name}&eventId(s)={ids}|marketId(s)={ids}[&outcomeId={id}]|outcomeId={id}[&market=&active=]&apiKey={key} - Native id mappings: our event (home, away, date, sport, league), market, hdp and side to the bookmaker's own event/market/outcome ids (Polymarket conditionId + CLOB token id, Kalshi contract ticker + yes/no), oriented like /odds, inactive rows kept with active=false; every response is {data, nextCursor}; bookmaker alone = bulk sync of upcoming and live events, paged with cursor and limit (paid plans only)
GET /participants?sport={slug}&apiKey={key} - Get teams/participants (esports rows add `game` and `shortCode`)
GET /participants/{id}/logo?apiKey={key} - Get participant crest as PNG (hotlinkable, cached 24h, 404 when none)
GET /bookmakers/selected?apiKey={key} - Get user's selected bookmakers
PUT /bookmakers/selected/select?bookmakers={list}&apiKey={key} - Select bookmakers

## Authentication

All endpoints except /sports, /bookmakers and /markets require an API key passed as query parameter:
?apiKey=YOUR_API_KEY

## Rate Limits

Paid plans: 5,000 requests/hour
Existing free keys: 100 requests/hour, capped at 500/day (new free keys are paused)
Additional packages: +10K/20K/30K requests/hour available (monthly plans only)

## Pricing (https://odds-api.io/pricing)

Solo £49/mo or £490/yr (2 bookmakers), Starter £99/mo or £990/yr (5), Growth £179/mo or £1,790/yr (10), Pro £229/mo or £2,290/yr (15). Annual = 10x monthly, 2 months free, card only. WebSocket streaming doubles the plan price. Checkout charges in GBP, USD, EUR, BRL, CNY, JPY or KRW.

## Supported Sports (34 total)

football, basketball, tennis, baseball, american-football, ice-hockey, esports, darts, mixed-martial-arts, boxing, handball, volleyball, snooker, table-tennis, rugby, cricket, water-polo, futsal, beach-volleyball, aussie-rules, floorball, squash, beach-soccer, lacrosse, curling, padel, bandy, gaelic-football, beach-handball, athletics, badminton, cross-country, golf, cycling

## Contact

Support: hello@odds-api.io
Status: https://status.odds-api.io (current API status and incident history)
Website: https://odds-api.io