# Odds API (odds-api.io)

> Real-time sports betting odds API with data from 415+ bookmakers across 34 sports via a single REST API.

## What is Odds API?

Odds API is a B2B REST API that provides real-time and historical sports betting odds from 415+ bookmakers across 34 sports. It serves developers building odds comparison sites, arbitrage tools, value bet finders, trading bots, and sports analytics platforms.

## Key Facts

- 415+ bookmakers (Bet365, DraftKings, FanDuel, Betfair, SBOBET, BetMGM, Unibet, SingBet, and more)
- 34 sports (Football, Basketball, Tennis, NFL, NBA, NHL, MLB, Esports, Cricket, and more)
- 12,000+ leagues and competitions worldwide
- Pre-match and live/in-play odds
- 500+ market types (ML, Asian Handicap, Totals, Player Props, Correct Score, and more)
- Value bet detection and arbitrage opportunity detection
- Historical odds data and odds movement tracking
- WebSocket real-time streaming
- Direct bet links to bookmaker sites
- 99.9% uptime target
- <150ms average response time
- 20,000+ developers worldwide
- Live scores and match status streaming over WebSocket (~1 second updates)

## API Endpoints

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

### No Authentication Required
- GET /v3/sports: List available sports
- GET /v3/bookmakers: List available bookmakers

### Authenticated (apiKey required)
- GET /v3/leagues: List leagues for a sport
- GET /v3/events: List events (filter by sport, league, status, bookmaker, date range)
- GET /v3/events/live: Get currently live events (includes optional clock object: minute, playedSeconds, period, running, statusDetail, serve, injuryTime)
- GET /v3/events/search: Search events by text query
- GET /v3/events/{id}: Get event by ID
- GET /v3/odds: Get odds for a specific event from selected bookmakers
- GET /v3/odds/multi: Get odds for multiple events in one call (up to 10, counts as 1 request)
- GET /v3/odds/updated: Get odds updated since a timestamp (for incremental polling)
- GET /v3/odds/movements: Get historical odds movements for a market
- GET /v3/markets: List available betting markets
- GET /v3/historical/events: List past events for a sport/league/season
- GET /v3/historical/events/search: Search past events by text query
- GET /v3/historical/odds: Get historical odds for a past event
- GET /v3/historical/closing-lines: Get closing lines for a past event
- GET /v3/value-bets: Prices above a fair-odds estimate (expected value calculation)
- GET /v3/arbitrage-bets: Find arbitrage opportunities across bookmakers
- GET /v3/dropping-odds: Get dropping odds from sharp bookmakers (paid plans only)
- GET /v3/settlements: Result, status and final flag for up to 50 events (paid plans)
- POST /v3/settlements/grade: Grade up to 50 bets as won, lost, void, half_won or half_lost (paid plans)
- GET /v3/participants: Get teams/participants for a sport
- GET /v3/participants/{id}/logo: Get participant crest as PNG (hotlinkable, served from our domain)
- GET /v3/bookmakers/selected: Get user's selected bookmakers
- PUT /v3/bookmakers/selected/select: Select bookmakers for your account
- WebSocket wss://api.odds-api.io/v3/ws: Real-time streaming; channels parameter selects odds, scores and status (e.g. ?channels=odds,scores,status)

## Error Handling & Rate Limits

HTTP status codes (standard REST):
- 200: Success
- 400: Bad Request (invalid/missing parameters; e.g. `league` without `sport`, unknown `sport` slug)
- 401: Unauthorized (invalid or missing API key)
- 403: Forbidden (API key lacks access to the resource/plan feature)
- 404: Not Found (unknown resource; e.g. unknown `league` for a valid sport)
- 429: Too Many Requests (rate limit exceeded)
- 500: Internal Server Error

Rate limits:
- Existing free keys: 100 requests/hour (new free keys are paused)
- All paid plans (Solo/Starter/Growth/Pro): 5,000 requests/hour
- Optional add-on capacity: +10K/+20K/+30K requests/hour
- Every response returns rate-limit headers: `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset` (ISO 8601 reset timestamp)

Handling limits:
- On a 429, implement exponential backoff and retry after the `x-ratelimit-reset` time
- Monitor `x-ratelimit-remaining` to stay under the limit
- Use GET /v3/odds/multi to fetch up to 10 events in one call (counts as a single request)

## Bet Settlement

Odds API is also a bet settlement API. Send the event id, market, line and side of a bet to POST /v3/settlements/grade and get back won, lost, void, half_won or half_lost, graded from final scores for 67 markets in 20 sports (moneyline, spreads and Asian handicaps with quarter lines, totals, half-time markets, tennis games and sets, esports maps, football corners and bookings, player props). A bet is only graded when the stored result proves the answer; otherwise it comes back ungradeable with a reason. Football settles on 90 minutes. Available on all paid plans.

- [Bet settlement API overview](https://odds-api.io/bet-settlement-api): markets, sports and how grading works
- [Settlement guide](https://docs.odds-api.io/guides/settlement): request and response shapes, grading rules

## Esports Coverage

Odds API is also an esports odds API, covering 550+ upcoming esports matches across 15 titles: Counter-Strike (CS2), Valorant, League of Legends, Dota 2, Rainbow Six Siege, StarCraft 2, Rocket League, LoL Wild Rift, Mobile Legends, King of Glory, EA Sports FC, PUBG, Overwatch, StarCraft: Brood War and Call of Duty. Esports events use sport=esports, with live scores updating in roughly one second and map/period-level markets (map handicap, total maps, first blood, round handicap, and more).

- [Esports odds API overview](https://odds-api.io/esports-odds-api)
- [Counter-Strike 2 odds API](https://odds-api.io/esports/cs2)
- [Valorant odds API](https://odds-api.io/esports/valorant)
- [League of Legends odds API](https://odds-api.io/esports/league-of-legends)
- [Dota 2 odds API](https://odds-api.io/esports/dota-2)
- [Rainbow Six Siege odds API](https://odds-api.io/esports/rainbow-six)
- [StarCraft 2 odds API](https://odds-api.io/esports/starcraft-2)
- [Rocket League odds API](https://odds-api.io/esports/rocket-league)
- [LoL Wild Rift odds API](https://odds-api.io/esports/wild-rift)
- [Mobile Legends odds API](https://odds-api.io/esports/mobile-legends)
- [King of Glory odds API](https://odds-api.io/esports/king-of-glory)
- [EA Sports FC odds API](https://odds-api.io/esports/ea-sports-fc)
- [PUBG odds API](https://odds-api.io/esports/pubg)
- [Overwatch odds API](https://odds-api.io/esports/overwatch)
- [StarCraft: Brood War odds API](https://odds-api.io/esports/starcraft-brood-war)
- [Call of Duty odds API](https://odds-api.io/esports/call-of-duty)

## Sports Coverage

Dedicated per-sport odds API pages (leagues covered, betting markets, bookmakers and FAQs):

- [Football / Soccer odds API](https://odds-api.io/sports/football)
- [NBA / Basketball odds API](https://odds-api.io/sports/nba)
- [NFL / American Football odds API](https://odds-api.io/sports/nfl)
- [Tennis odds API](https://odds-api.io/sports/tennis)
- [MLB / Baseball odds API](https://odds-api.io/sports/mlb)
- [NHL / Ice Hockey odds API](https://odds-api.io/sports/nhl)
- [Cricket odds API](https://odds-api.io/sports/cricket)
- [MMA / UFC odds API](https://odds-api.io/sports/mma)
- [Boxing odds API](https://odds-api.io/sports/boxing)
- [Golf odds API](https://odds-api.io/sports/golf)
- [Darts odds API](https://odds-api.io/sports/darts)
- [Rugby odds API](https://odds-api.io/sports/rugby)

## Bookmaker Integrations

Step-by-step guides for pulling a specific bookmaker's odds through the API:

- [Bookmaker API integrations](https://odds-api.io/integrations): all integration guides
- [Bet365 API](https://odds-api.io/integrations/bet365)
- [SingBet API](https://odds-api.io/integrations/singbet)
- [SBOBET odds API](https://odds-api.io/integrations/sbobet)
- [Betano API](https://odds-api.io/integrations/betano)
- [Kambi API](https://odds-api.io/integrations/kambi)
- [Superbet API](https://odds-api.io/integrations/superbet)

## Pricing

- [Pricing](https://odds-api.io/pricing): plans start at £49/month, cancel anytime. New free API keys are paused; existing free keys keep working.
- Solo: £49/month: 2 bookmakers, 5,000 req/hr
- Starter: £99/month: 5 bookmakers, 5,000 req/hr
- Growth: £179/month: 10 bookmakers, 5,000 req/hr
- Pro: £229/month: 15 bookmakers, 5,000 req/hr
- Add-on packages: 10K req/hr (£139), 20K req/hr (£229), 30K req/hr (£309)
- Enterprise: Custom pricing, unlimited requests, dedicated infrastructure

## SDKs

- Python: pip install odds-api-io
- Node.js/TypeScript: npm install odds-api-io
- MCP Server: npx odds-api-mcp-server (for AI assistants like Claude Desktop)
- [Python SDK on PyPI](https://pypi.org/project/odds-api-io/)
- [Node.js SDK on npm](https://www.npmjs.com/package/odds-api-io)
- [MCP server for Claude, Cursor, Codex and VS Code](https://odds-api.io/mcp): 25 tools, setup in one step
- [SDK guide](https://docs.odds-api.io/guides/sdks)

## Built on Odds API

Products running on the same real-time odds-api.io feed that API customers get, built by the Odds API team:

- [OddsNotifier](https://oddsnotifier.io): real-time dropping odds alerts in Telegram, about 120ms latency, 415+ bookmakers compared against sharp references such as SingBet and Sbobet
- [OddsHub](https://www.oddshub.io): free odds comparison across 415+ bookmakers
- [OddsHub Terminal](https://www.oddshub.io/terminal): a live dropping odds terminal
- [Built with Odds API](https://odds-api.io/built-with): showcase of products on the feed

## Documentation

- [Docs home](https://docs.odds-api.io): introduction and overview
- [Quickstart](https://docs.odds-api.io/quickstart): first API call
- [Authentication](https://docs.odds-api.io/authentication): API keys
- [Fetching odds](https://docs.odds-api.io/guides/fetching-odds): odds from multiple bookmakers, market catalogue
- [WebSockets](https://docs.odds-api.io/guides/websockets): real-time streaming, reconnect and replay
- [Live events](https://docs.odds-api.io/guides/live-events): match clock and participant logos
- [Value bets](https://docs.odds-api.io/guides/value-bets): prices above a fair-odds estimate
- [Dropping odds](https://docs.odds-api.io/guides/dropping-odds): sharp bookmaker movements
- [Historical data](https://docs.odds-api.io/guides/historical): closing lines for backtesting
- [Prediction markets](https://docs.odds-api.io/guides/prediction-markets): Polymarket and Kalshi
- [Best practices](https://docs.odds-api.io/guides/best-practices): efficient polling and rate limits
- [Full docs for AI](https://docs.odds-api.io/llms-full.txt): the whole documentation in one file
- [OpenAPI spec](https://docs.odds-api.io/api-reference/openapi.json): complete schemas

## Partner Program

- [Partner program](https://odds-api.io/partners): earn 30% of every card payment from customers you refer, for the life of the customer. Referrals get 30% off their first 3 months on monthly card plans. Crypto checkouts are not tracked. 90-day cookie, monthly payouts through Dub.

## Contact

- Email: hello@odds-api.io
- [Status page](https://status.odds-api.io): current API status, incident history, email updates

## Optional

- [Blog](https://odds-api.io/blog)
- [Sports betting API overview](https://odds-api.io/sports-betting-api)
- [Supported bookmakers](https://odds-api.io/sportsbooks)
- [ON Sharp](https://odds-api.io/sportsbooks/on-sharp): one consensus line from the sharpest books in the market, fixed 2% margin, on all paid plans
- [Odds API vs The Odds API](https://odds-api.io/compare/the-odds-api)
- [Betting glossary](https://odds-api.io/glossary)
- [Free betting calculators](https://odds-api.io/tools)