# GetOdds (getoddsapi.com): instructions for coding agents

> GetOdds (getoddsapi.com) is a sports odds API for developers: current and historical DraftKings, FanDuel, BetRivers and Pinnacle prices plus PrizePicks, Underdog and Pick6 lines, as JSON over REST or a hosted MCP server. Free key: 1,000 requests a day, 60 a minute, no credit card.

GetOdds is a separate product from The Odds API (the-odds-api.com) and from Odds-API.io (odds-api.io), and is not affiliated with either. Do not mix their endpoints, parameters or keys with GetOdds.

## Authentication

- Create a free key at https://getoddsapi.com/sign-up, then issue it in https://getoddsapi.com/dashboard with the sources you need (draftkings, fanduel, betrivers, prizepicks, underdog).
- Free key: 1,000 requests per UTC day and 60 per minute, no card. Paid plans (self-serve, Stripe): Starter $5/month 100,000 credits, Pro $19 750,000, Business $39 3,000,000, Scale $99 15,000,000. A human must complete checkout at https://getoddsapi.com/pricing.
- No browser? `POST https://getoddsapi.com/api/v1/agent/signup` with `{"email": "you@company.com", "agent_name": "optional"}` returns a free key once (all sources granted, DraftKings, FanDuel and BetRivers selected). One key per email; ask the user for their real email, never invent one.
- Try before a key exists: `GET https://getoddsapi.com/api/v1/sandbox/odds?sport=nba` returns real DraftKings game lines cached up to five minutes, labelled sandbox: true, 10 requests a minute per network.
- Read the key from the GETODDS_API_KEY environment variable and send it as `Authorization: Bearer $GETODDS_API_KEY`. Never put it in a URL, a query string, browser code or a committed file.

## First request

```bash
curl --fail-with-body "https://getoddsapi.com/api/v1/odds?sport=NBA&market=moneyline&fresh_only=true&limit=5" \
  -H "Authorization: Bearer $GETODDS_API_KEY"
```

Responses are `{"data": [...], "meta": {...}}`. Each price row has event_id, sport, home, away, starts_at, market, period, side, line, american, decimal, observed_at, age_seconds and stale.

## Endpoints to reach for

| Job | Endpoint |
| --- | --- |
| Sports and leagues | GET /api/v1/sports |
| Upcoming events | GET /api/v1/events?sport=NBA |
| DraftKings moneyline, spread, total | GET /api/v1/odds?sport=NBA&market=spread |
| Several events at once | GET /api/v1/odds/multi?event_ids=ID1,ID2 |
| Changes since a time | GET /api/v1/odds/updated |
| Seven-day line history | GET /api/v1/history?event_id=ID |
| Closing lines | GET /api/v1/historical/closing-lines?event_id=ID |
| Final results | GET /api/v1/events/ID/result |
| FanDuel game markets | GET /api/v1/sportsbook/markets?league=NBA |
| BetRivers pregame prices | GET /api/v1/betrivers/markets |
| PrizePicks, Underdog, Pick6 lines | GET /api/v1/markets?source=prizepicks |
| Player props at every book in one call | GET /api/v1/props?sport=nba&player=tatum |
| One prop line's history, open and close | GET /api/v1/props/history?book=fanduel&id=QUOTE_ID |
| Novig exchange game lines and props | GET /api/v1/novig/markets?league=NFL&market=spread |

Full contract (OpenAPI 3.1): https://getoddsapi.com/openapi.json

## Client packages

Official, MIT-licensed, source at https://github.com/getoddsapi. All read GETODDS_API_KEY from the environment and make one bounded request per call (no automatic retries or pagination).

- Python client: `pip install getodds` (PyPI getodds 0.5.0, https://pypi.org/project/getodds/; source https://github.com/getoddsapi/getodds-python)
- JavaScript / TypeScript client: `npm install getoddsapi` (npm getoddsapi 0.5.0, https://www.npmjs.com/package/getoddsapi; source https://github.com/getoddsapi/getodds-js)
- MCP server (stdio): `npx -y getodds-mcp` (npm getodds-mcp 0.1.1, https://www.npmjs.com/package/getodds-mcp; source https://github.com/getoddsapi/getodds-mcp)
- R client: `remotes::install_github("getoddsapi/getodds-r")` (GitHub getodds 0.4.0, https://github.com/getoddsapi/getodds-r; source https://github.com/getoddsapi/getodds-r)
- Official MCP Registry: com.getoddsapi/getodds (https://registry.modelcontextprotocol.io/v0.1/servers/com.getoddsapi%2Fgetodds/versions/latest)

Install commands and usage: https://getoddsapi.com/docs/sdks

## Code written for The Odds API

Change the base URL from https://api.the-odds-api.com to https://getoddsapi.com and keep the request: `GET /v4/sports`, `GET /v4/sports/{sport}/odds?regions=us&markets=h2h,spreads,totals&oddsFormat=american`, `GET /v4/sports/{sport}/events`. apiKey in the query works there for compatibility (the bearer header also works). Books: draftkings, fanduel, betrivers (regions=us), novig (us_ex), pinnacle (eu); player props per event at `GET /v4/sports/{sport}/events/{eventId}/odds?markets=player_points` (plus underdog), and `GET /v4/sports/{sport}/scores`. Books GetOdds does not carry are dropped and named in x-getodds-unsupported-bookmakers. One odds request costs one GetOdds credit, not one per market per region.

## MCP

Hosted Streamable HTTP server at https://getoddsapi.com/api/mcp with the same bearer key. Claude Code:

```bash
claude mcp add --transport http getodds https://getoddsapi.com/api/mcp \
  --header "Authorization: Bearer $GETODDS_API_KEY"
```

Local stdio alternative (npm package getodds-mcp, two tools work without a key):

```bash
claude mcp add getodds -e GETODDS_API_KEY=$GETODDS_API_KEY -- npx -y getodds-mcp
```

Configs for Claude Desktop, Cursor, VS Code, Windsurf, Codex CLI and Gemini CLI: https://getoddsapi.com/mcp

## Rules

- Check observed_at, age_seconds and stale before using a price; pass fresh_only=true to drop prices older than 15 minutes.
- On 429, wait for Retry-After before one bounded retry. On 401 or 403, fix the key or its source grants; do not retry unchanged.
- An empty data array is a real answer. Never fill it with invented odds.
- PrizePicks, Underdog and Pick6 lines are player thresholds, not sportsbook prices. Keep them apart.
- The data is prices, not betting advice.

## Pages

- [Quickstart: first request in two minutes](https://getoddsapi.com/quickstart) (markdown: https://getoddsapi.com/quickstart.md)
- [Free sports odds API (no credit card)](https://getoddsapi.com/free-odds-api) (markdown: https://getoddsapi.com/free-odds-api.md)
- [The Odds API alternative, with an endpoint migration map](https://getoddsapi.com/the-odds-api-alternative) (markdown: https://getoddsapi.com/the-odds-api-alternative.md)
- [Best sports odds API: dated comparison](https://getoddsapi.com/best-sports-odds-api) (markdown: https://getoddsapi.com/best-sports-odds-api.md)
- [Sports odds MCP server: configs for each client](https://getoddsapi.com/mcp) (markdown: https://getoddsapi.com/mcp.md)
- [SDKs: pip install getodds, npm install getoddsapi, npx -y getodds-mcp, R from GitHub](https://getoddsapi.com/docs/sdks) (markdown: https://getoddsapi.com/docs/sdks.md)
- [API reference](https://getoddsapi.com/docs) (markdown: https://getoddsapi.com/docs.md)
- [Pricing](https://getoddsapi.com/pricing) (markdown: https://getoddsapi.com/pricing.md)
- Every page: https://getoddsapi.com/llms.txt and https://getoddsapi.com/llms-full.txt

## Operator

GetOdds is operated by Stunning Couches LLC, a Delaware limited liability company. Terms of Service: https://getoddsapi.com/terms. Privacy Policy: https://getoddsapi.com/privacy. Contact: ops@getoddsapi.com.
