# 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 365 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`, add `markets` to shrink payloads.

## 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
https://docs.odds-api.io/guides/live-events - Live events, match clock and participant logos
https://docs.odds-api.io/guides/value-bets - Find positive expected value betting opportunities
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/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/paying-with-crypto - Pay with BTC, ETH, USDC and 70+ 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

- `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 and will stop being accepted
- Each WebSocket update includes a globally increasing `seq`
- Reconnect with `lastSeq` to receive a compacted replay of missed updates
- Replay is latest-state per `eventId:bookie`, not every intermediate tick
- 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 - 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 (top-level `home`/`away` is the OT/penalty-inclusive result):
- `p1`, `p2`, ... `pN` - period / set / quarter scores
- `ft` - full-time / regulation result
- `ot` - overtime / extra time / extra innings (when played)
- `ap` - penalty shootout tally (when decided on penalties)
- `currentgame` - current game points (live tennis)
- `map1`, `map2`, ... - per-map scores (esports)

So football uses `p1` + `ft`; ice hockey uses `p1`, `p2`, `p3`, `ft` (+ `ot`); basketball `p1`–`p4`, `ft` (+ `ot`). The full-time key is `ft` (the legacy feed used `fulltime`).

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 and createdAt (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. 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). 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 recently updated odds (returns X-Server-Time/X-Next-Since headers for delta polling)
GET /odds/movements?eventId={id}&bookmaker={name}&market={name}&apiKey={key} - Get odds movement history. History is recorded only for a fixed set of bookmakers: Bet365, 12bet, DraftKings, FanDuel, FB Sports, GG.bet, M88, Norsk Tipping, ON Sharp, Sbobet, SingBet, Superbet, Veikkaus, and selected sharp books. Other bookmakers return a 404
GET /value-bets?bookmaker={name}&apiKey={key} - Get value betting opportunities (optional: sport={slug}, league={slug} requires sport, includeEventDetails)
GET /arbitrage-bets?bookmakers={list}&apiKey={key} - Get arbitrage opportunities
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 /participants?sport={slug}&apiKey={key} - Get teams/participants
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. Card payments carry a 7-day money-back guarantee.

## 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
Website: https://odds-api.io