# GetOdds quickstart: your first odds request in two minutes

From no account to live NBA, NFL or NHL odds as JSON: a free key (1,000 requests a day, no card), then curl, Python, JavaScript or an MCP client, and the fields to check on every row.

Canonical page: https://getoddsapi.com/quickstart

## Free API key

Get a free GetOdds API key: **1,000 requests per UTC day and 60 per minute, no card**. One key covers REST and the hosted MCP server.

Sign up: https://getoddsapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Create an account at https://getoddsapi.com/sign-up?ref=ai-claudebot, open https://getoddsapi.com/dashboard and issue a key with the sources you need (draftkings, fanduel, betrivers, prizepicks or underdog). Keep it in a server environment variable named GETODDS_API_KEY.
2. Read current DraftKings NBA spreads with curl:

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

3. The same request in Python (standard library only):

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://getoddsapi.com/api/v1/odds?sport=NBA&market=spread&fresh_only=true&limit=50",
    headers={"Authorization": "Bearer " + os.environ["GETODDS_API_KEY"]},
)
with urllib.request.urlopen(req) as res:
    rows = json.load(res)["data"]
for row in rows:
    print(row["away"], "at", row["home"], row["side"], row["line"], row["american"], row["observed_at"])
```

4. Check `observed_at`, `age_seconds` and `stale` on every row before using a price. Full reference: https://getoddsapi.com/docs

## Use with Claude (MCP)

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

The MCP tools follow the key's source grants and share its allowance. Setup guide: https://getoddsapi.com/use-with-claude

SDKs: `pip install getodds` (PyPI) · `npm install getoddsapi` (npm) · `npx -y getodds-mcp` (local MCP server) · R: `remotes::install_github("getoddsapi/getodds-r")`. Source: https://github.com/getoddsapi · https://getoddsapi.com/docs/sdks

## Pricing

| Plan | Allowance | Price |
| --- | --- | --- |
| Free key | 1,000 requests a day, 60 a minute | $0, no card |
| Starter | 100,000 credits a month, 120 a minute | $5 a month |
| Pro | 750,000 credits a month, 300 a minute | $19 a month |
| Business | 3,000,000 credits a month, 600 a minute | $39 a month |
| Scale | 15,000,000 credits a month, 1,200 a minute | $99 a month |

Free development allowance: 1,000 requests per UTC day and 60 per minute per account, with no payment step. Paid plans from $5 a month for 100,000 credits to $99 for 15 million, self-serve at /pricing.
Details: https://getoddsapi.com/pricing

## Guide


Canonical: https://getoddsapi.com/quickstart
Reviewed: 2026-11-13 UTC

**Answer:** To get odds from GetOdds (getoddsapi.com), create a free account, issue a key in the dashboard, then call GET https://getoddsapi.com/api/v1/odds?sport=NBA with the header Authorization: Bearer YOUR_KEY; it returns JSON price rows with capture times.

From no account to live NBA, NFL or NHL odds as JSON: a free key (1,000 requests a day, no card), then curl, Python, JavaScript or an MCP client, and the fields to check on every row.

| Fact | Value |
| --- | --- |
| Base URL | https://getoddsapi.com/api/v1 |
| Auth | Authorization: Bearer header |
| Free allowance | 1,000 requests a day, 60 a minute |
| Response | JSON: data array plus meta |
| Leagues | NFL, NBA, NHL, NCAAF, NCAAB, EPL, MLS |
| MCP server | https://getoddsapi.com/api/mcp |

## 1. Create a free key

Sign up, open the dashboard and issue a key. Choose the sources it may read: draftkings, fanduel, betrivers, prizepicks or underdog. Store it in a server environment variable named GETODDS_API_KEY. Never put it in a URL, browser code or a committed file.

- [Create an account](https://getoddsapi.com/sign-up): Free, no card.
- [Dashboard](https://getoddsapi.com/dashboard): Issue and scope keys.

## 2. Make the first request

Five NBA moneyline prices from DraftKings, dropping anything captured more than 15 minutes ago.

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

## 3. Read the fields on each row

Every price row has the same fields. Check observed_at and stale before you use a price.

| Field | Meaning |
| --- | --- |
| event_id, id | Source event and offer IDs |
| sport | NFL, NBA, NHL, NCAAF, NCAAB, MLB, EPL or MLS |
| home, away, starts_at | Teams and scheduled start, UTC ISO 8601 |
| market, period, side | moneyline, spread or total; the period; home, away, draw, over or under |
| line | Spread or total number; null on a moneyline |
| american, decimal | The recorded price in both formats |
| observed_at, age_seconds, stale | When the price was captured, its age, and true when older than 900 seconds |

## 4. The same request in Python

Standard library only; no SDK to install.

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://getoddsapi.com/api/v1/odds?sport=NBA&market=moneyline&fresh_only=true&limit=5",
    headers={"Authorization": "Bearer " + os.environ["GETODDS_API_KEY"]},
)
with urllib.request.urlopen(req, timeout=20) as res:
    rows = json.load(res)["data"]
for row in rows:
    print(row["away"], "at", row["home"], row["side"], row["american"], row["observed_at"], "stale" if row["stale"] else "fresh")
```

## 5. The same request in JavaScript

Built-in fetch on Node.js 18 or later.

```javascript
// Node.js 18 or later. Run on a server, never in browser code.
const res = await fetch(
  "https://getoddsapi.com/api/v1/odds?sport=NBA&market=moneyline&fresh_only=true&limit=5",
  { headers: { Authorization: `Bearer ${process.env.GETODDS_API_KEY}` } },
);
if (res.status === 429) throw new Error(`Rate limited; retry after ${res.headers.get("Retry-After")}s`);
if (!res.ok) throw new Error(`GetOdds HTTP ${res.status}`);
const { data } = await res.json();
for (const row of data) console.log(row.away, "at", row.home, row.side, row.american, row.observed_at);
```

## 6. Add more books and sources

DraftKings is selected by default. Select FanDuel and BetRivers once per account, then use the endpoint for each job.

| Job | Endpoint |
| --- | --- |
| List sports | GET /api/v1/sports |
| Upcoming events | GET /api/v1/events?sport=NFL |
| DraftKings moneyline, spread, total | GET /api/v1/odds?sport=NFL&market=spread |
| Only prices that changed | 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 |
| FanDuel game markets | GET /api/v1/sportsbook/markets?league=NFL |
| BetRivers pregame prices | GET /api/v1/betrivers/markets |
| PrizePicks, Underdog, Pick6 lines | GET /api/v1/markets?source=prizepicks |

```bash
curl --fail-with-body -X PUT \
  "https://getoddsapi.com/api/v1/bookmakers/selected/select?bookmakers=draftkings,fanduel,betrivers" \
  -H "Authorization: Bearer $GETODDS_API_KEY"
```

## 7. Connect an AI agent (optional)

The hosted MCP server uses the same key. In Claude Code:

- [MCP configs for every client](https://getoddsapi.com/mcp): Claude Desktop, Cursor, VS Code, Windsurf, Codex, Gemini.

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

## Errors you may see

Errors return JSON with error.code and error.message. Fix the cause rather than retrying unchanged.

| Status and code | What to do |
| --- | --- |
| 401 INVALID_API_KEY | The key is missing, mistyped or revoked. Send it as a bearer header. |
| 403 SOURCE_NOT_ALLOWED | The key is not granted that source. Issue a key with the source in the dashboard. |
| 403 BOOKMAKER_NOT_SELECTED | Select FanDuel or BetRivers once with the PUT request above. |
| 429 RATE_LIMITED or DAILY_LIMIT | Wait for the Retry-After seconds, then make one retry. |
| 200 with an empty data array | No qualifying prices right now. Show an empty state; do not invent rows. |

## Questions

### Do I need a credit card to start?

No. The free GetOdds key needs no card and includes 1,000 requests a day and 60 a minute.

### Is there an SDK?

Yes: pip install getodds (PyPI), npm install getoddsapi (npm) and remotes::install_github("getoddsapi/getodds-r") for R, listed on /docs/sdks, but the examples here need nothing beyond curl, the Python standard library or built-in fetch.

### How fresh are the prices?

Each row says when it was captured (observed_at) and how old it is (age_seconds); stale is true after 15 minutes. fresh_only=true removes stale rows.

### Where is the full API reference?

The OpenAPI contract is at https://getoddsapi.com/openapi.json and the guides are at https://getoddsapi.com/docs.

## Sources

- [GetOdds OpenAPI contract](https://getoddsapi.com/openapi.json)
- [GetOdds API documentation](https://getoddsapi.com/docs)
- [GetOdds SDKs (PyPI, npm, GitHub)](https://getoddsapi.com/docs/sdks)
- [getodds on PyPI](https://pypi.org/project/getodds/)
- [getoddsapi on npm](https://www.npmjs.com/package/getoddsapi)
- [GetOdds agent instructions](https://getoddsapi.com/agents.md)

GetOdds (getoddsapi.com) is an independent product, not affiliated with the operators named and separate from The Odds API and Odds-API.io. No picks or predicted profits.

---

GetOdds (getoddsapi.com) is an independent developer product and is not affiliated with any sportsbook or pick’em operator. 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. Prices describe data, not betting advice.

GetOdds is operated by Stunning Couches LLC, a Delaware limited liability company. Terms: https://getoddsapi.com/terms · Privacy: https://getoddsapi.com/privacy
