# HoopsAPI

> Basketball odds from multiple bookmakers. One API. Real-time moneyline, handicap, and over/under odds across NBA, Euroleague, and 100+ competitions.

Basketball odds from multiple bookmakers. One API.

Bookmakers: 1xbet, betway, fanduel, pinnacle, smarkets, unibet. Odds refresh every 10 minutes.

**Periods:** `ft` (full game, including overtime), `h1`, `h2`, `q1`–`q4`.

**Markets:** `moneyline`, `spread` (`line` is the home team's handicap: -4.5 means home gives 4.5), `total`, `team_total_home`, `team_total_away`.

**Main line:** where a bookmaker offers several lines, the main one is the most evenly priced.

Authenticate with an API key as a bearer token: `Authorization: Bearer YOUR_API_KEY`. A free key comes with sign-up.

## Docs

- [API reference](https://hoopsapi.com/docs): every endpoint, parameter and response schema
- [OpenAPI spec](https://hoopsapi.com/openapi.json): machine-readable, OpenAPI 3.1
- [Pricing](https://hoopsapi.com/pricing): plans and request limits
- [Sign up](https://hoopsapi.com/sign-up): free API key, no credit card

## MCP server

Remote MCP server (Streamable HTTP) at https://hoopsapi.com/mcp, authenticated with the same API key: `Authorization: Bearer YOUR_API_KEY`. Each tool call counts as one API request. Setup for Claude, ChatGPT, Claude Code, Codex and GitHub Copilot: https://hoopsapi.com/ai

- list_competitions: Competitions with upcoming games, to find exact names
- list_games: Upcoming games in a competition with every bookmaker's main lines
- get_game: One game with every period, alternate lines on request; closing odds after tip-off
- get_game_history: Every price change for a game (Data plan)
- list_discrepancies: Biggest cross-bookmaker gaps (Pro and Data plans)
- list_providers: Bookmakers covered and when each was last collected

## Features

- [Basketball Handicap (Spread) Odds API](https://hoopsapi.com/features/spread-odds-api): Point-spread odds from multiple bookmakers with every alternate line, normalised to the home team's handicap.
- [Basketball Totals and Team Totals Odds API](https://hoopsapi.com/features/totals-odds-api): Over/under odds for the game and for each team, with alternate lines, from multiple bookmakers.
- [Basketball Quarter and Half Odds API](https://hoopsapi.com/features/quarter-and-half-odds-api): Handicap and totals odds for every half and quarter, not just the full game.
- [Historical Basketball Odds and Closing Lines API](https://hoopsapi.com/features/historical-odds-api): Every price change for a game and the closing odds of finished games, for backtesting and model evaluation.
- [Historical Basketball Odds Data: Bulk JSON Downloads](https://hoopsapi.com/historical-data): Download NBA odds data by season as JSON: every price change of the current season, and results with closing odds for every game since 2021-22.

## Leagues

- [NBA Odds API](https://hoopsapi.com/leagues/nba): NBA odds API: live moneyline, spread and totals for every NBA game from 6 bookmakers including Pinnacle, plus quarter and half lines. JSON, free tier.
- [EuroLeague Odds API](https://hoopsapi.com/leagues/euroleague): EuroLeague moneyline, handicap and totals odds from multiple bookmakers, with quarter and half markets, in one API.
- [Liga ACB Odds API: Live Spanish Basketball Odds](https://hoopsapi.com/leagues/acb): Every Liga ACB game's moneyline, handicap and total from 6 bookmakers including Pinnacle, refreshed every 10 minutes. See this week's lines below; free API key.
- [Australian NBL Odds API](https://hoopsapi.com/leagues/nbl): Australian NBL moneyline, handicap and totals odds from multiple bookmakers in one API.
- [College Basketball (NCAA) Odds API](https://hoopsapi.com/leagues/ncaab): NCAA college basketball odds API: moneyline, spread and totals for men's Division I games from multiple bookmakers, through March Madness. JSON, free tier.

## Guides

- [How to Remove the Bookmaker Margin from Odds](https://hoopsapi.com/guides/remove-bookmaker-margin): Turn bookmaker odds into fair probabilities: the proportional and power methods, worked examples and Python code.
- [Closing Line Value: What It Is and How to Measure It](https://hoopsapi.com/guides/closing-line-value): Why the closing price is the benchmark for any betting model, and how to measure CLV from odds history.
- [How Much Do Basketball Odds Differ Between Bookmakers?](https://hoopsapi.com/guides/compare-basketball-odds): Margins and price gaps across bookmakers, from NBA to minor leagues, measured on live odds.

## Endpoints

- GET https://hoopsapi.com/api/v1/games: List Games. Upcoming games that have odds, with each bookmaker's main lines for every period.
  - competition (query, optional): Filter by competition name, case-insensitive (e.g. NBA)
- GET https://hoopsapi.com/api/v1/games/{game_id}: Get Game. One game with every alternate line. Finished games are served from the archive with their closing odds.
  - game_id (path, required)
- GET https://hoopsapi.com/api/v1/games/{game_id}/history: Get Game History. Every price change for a game, newest first (Data plan). Works for upcoming and finished games.
  - game_id (path, required)
  - provider (query, optional): Only this bookmaker
  - market (query, optional, one of moneyline, spread, total, team_total_home, team_total_away): Only this market
  - period (query, optional, one of ft, h1, h2, q1, q2, q3, q4): Only this period
  - limit (query, optional, default 500): Max changes to return
- GET https://hoopsapi.com/api/v1/competitions: List Competitions
- GET https://hoopsapi.com/api/v1/providers: List Providers. Bookmakers and how fresh their data is.
- GET https://hoopsapi.com/api/v1/discrepancies: List Discrepancies. Biggest cross-bookmaker gaps in main lines: moneyline prices, handicap lines and totals (Pro and Data plans).
  - competition (query, optional): Filter by competition name
  - limit (query, optional, default 5): Top N per category
  - period (query, optional, one of ft, h1, h2, q1, q2, q3, q4, default ft): Period to compare
- GET https://hoopsapi.com/api/health: Health

## Plans

- Free: €0/month, 10 requests/day
- Starter: €10/month, 500 requests/day
- Pro: €49/month, 5,000 requests/day, includes discrepancies
- Data: €100/month, 20,000 requests/day, includes discrepancies and price history