# Underdog API SDKs and packages

> Install the Underdog API clients: pip install underdog-api, npm install underdog-api, npx -y underdog-api-mcp. Source on GitHub, copy-paste examples for the board, line moves and graded results. Underdog API (https://underdogapi.com) is an independent Underdog Fantasy pick'em data API: Higher/Lower lines with separate payout multipliers per side, line history, changes and graded results as JSON, CSV, MCP and streams.

Canonical page: https://underdogapi.com/sdks

## Free offer

**Free API key, no card: 100 credits a month** on the live board, every league, separate Higher/Lower prices, and the last 24 hours of line history. Sign up: https://underdogapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Get a free key at https://underdogapi.com/sign-up?ref=ai-claudebot (no card), or let your agent request one: `POST https://underdogapi.com/api/v1/agent/signup` with `data_wanted` and `use_case`, then show your user the returned approval_url.
2. Export it: `export UNDERDOG_API_KEY=ud_...`
3. First call with curl:

```bash
curl --fail-with-body 'https://underdogapi.com/api/v1/projections?league=NBA&view=compact&limit=5' \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: NBA dashboard integration check'
```

4. Same call in Python:

```python
import os, requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"league": "NBA", "view": "compact", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
)
r.raise_for_status()
for line in r.json()["data"]:
    print(line["player"]["name"], line["market"]["stat"], line["line"])
```

## Use it from Claude (MCP)

Claude Code, one command:

```bash
claude mcp add --transport http underdog https://underdogapi.com/api/mcp --header "Authorization: Bearer $UNDERDOG_API_KEY"
```

Or add this server to your Claude MCP configuration (the key stays in the environment):

```json
{
  "mcpServers": {
    "underdog": {
      "type": "http",
      "url": "https://underdogapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNDERDOG_API_KEY}"
      }
    }
  }
}
```

Guide: https://underdogapi.com/use-with-claude

## SDKs and packages

Official clients for Underdog API (independent; not Underdog Fantasy). Source: https://github.com/underdogapi · Overview: https://underdogapi.com/sdks

- Python SDK: `pip install underdog-api` (PyPI: https://pypi.org/project/underdog-api/ · source: https://github.com/underdogapi/underdogapi-python)
- JavaScript / TypeScript SDK: `npm install underdog-api` (npm: https://www.npmjs.com/package/underdog-api · source: https://github.com/underdogapi/underdogapi-js)
- MCP server (stdio): `npx -y underdog-api-mcp` (npm: https://www.npmjs.com/package/underdog-api-mcp · source: https://github.com/underdogapi/underdogapi-mcp)

Python:

```python
from underdog_api import Client

ud = Client()  # reads UNDERDOG_API_KEY
board = ud.projections(league="NBA", view="compact", limit=20)
for line in board["data"]:
    print(line)
print(board["meta"]["observed_at"])
```

Claude Code with the stdio MCP package (the hosted server at /api/mcp needs no install):

```bash
claude mcp add underdog -e UNDERDOG_API_KEY=ud_... -- npx -y underdog-api-mcp
```

## Pricing

| Plan | Price | Credits / month | Notes |
| --- | --- | --- | --- |
| Free | $0 | 100 | No card. Live feed 5 minutes behind; last 24 hours of line history |
| Developer | $49/month | 10,000 | For models that need full training pages and loaded game-log seasons. Live feed, no added plan delay |
| Production | $149/month | 50,000 | For apps with real users and push delivery. Everything in Developer, signed webhooks for every change |
| Scale | $499/month | 250,000 | For apps whose traffic has outgrown Production. Everything in Production, 15 live-feed connections at once |

Full pricing: https://underdogapi.com/pricing

## On this page

SDKs · updated November 15, 2026



Short answer: Underdog API has official clients: `pip install underdog-api` (Python, PyPI), `npm install underdog-api` (JavaScript and TypeScript, npm) and `npx -y underdog-api-mcp` (a stdio MCP server, npm), all open source at https://github.com/underdogapi; each reads a free key (100 credits a month, no card) from UNDERDOG_API_KEY and returns Underdog Fantasy pick'em lines with separate Higher and Lower multipliers, line history and graded results.

## Packages

| Python SDK | pip install underdog-api · PyPI: https://pypi.org/project/underdog-api/ |
| --- | --- |
| JavaScript / TypeScript SDK | npm install underdog-api · npm: https://www.npmjs.com/package/underdog-api |
| MCP server (stdio) | npx -y underdog-api-mcp · npm: https://www.npmjs.com/package/underdog-api-mcp |
| Source code | https://github.com/underdogapi (MIT license) |
| Python import name | underdog_api (package name underdog-api) |
| Dependencies | None: the Python client uses the standard library, the JS client and the MCP server use the platform fetch |
| Key | One UNDERDOG_API_KEY for REST, SDKs and MCP; free plan 100 credits a month, no card |
| Hosted MCP (no install) | https://underdogapi.com/api/mcp (Streamable HTTP, bearer key) |
| Run by | Underdog API (underdogapi.com), an independent data service; not Underdog Fantasy |

[Get a free API key](https://underdogapi.com/sign-up) [API reference](https://underdogapi.com/docs)

## Install

Set UNDERDOG_API_KEY first. A free key takes a minute and needs no card.

shell

```
pip install underdog-api      # Python
npm install underdog-api      # JavaScript / TypeScript
npx -y underdog-api-mcp     # stdio MCP server
export UNDERDOG_API_KEY=ud_...   # free key: https://underdogapi.com/sign-up
```

| Package | Install | Links |
| --- | --- | --- |
| Python SDK Python 3.9+ | pip install underdog-api | [PyPI](https://pypi.org/project/underdog-api/) · [GitHub](https://github.com/underdogapi/underdogapi-python) |
| JavaScript / TypeScript SDK Node 18+, Deno, Bun, edge runtimes | npm install underdog-api | [npm](https://www.npmjs.com/package/underdog-api) · [GitHub](https://github.com/underdogapi/underdogapi-js) |
| MCP server (stdio) Node 18+ | npx -y underdog-api-mcp | [npm](https://www.npmjs.com/package/underdog-api-mcp) · [GitHub](https://github.com/underdogapi/underdogapi-mcp) |

## Python

Standard library only. Board, changes, past boards, graded results, paging and retries; import name underdog_api. [PyPI](https://pypi.org/project/underdog-api/) · [source](https://github.com/underdogapi/underdogapi-python)

python

```
from underdog_api import Client

ud = Client()  # reads UNDERDOG_API_KEY
board = ud.projections(league="NBA", view="compact", limit=20)
for line in board["data"]:
    print(line)
print(board["meta"]["observed_at"])
```

python · line moves and past boards

```
for change in ud.pages("/api/v1/changes", league="NFL", event_type="line.moved", limit=200):
    print(change["observed_at"], change["player_name"], change["stat"], change["previous_line"], "->", change["line"])

past = ud.board(as_of="2026-11-14T23:00:00Z", league="NHL", limit=100)   # paid plans
graded = ud.results(league="NBA", date="2026-11-13", limit=200)       # paid plans
```

## JavaScript and TypeScript

No dependencies, platform fetch, types included. Same methods as the Python client, with async paging. Keep the key on a server or edge function. [npm](https://www.npmjs.com/package/underdog-api) · [source](https://github.com/underdogapi/underdogapi-js)

javascript

```
import { Underdog } from 'underdog-api';

const ud = new Underdog();   // reads UNDERDOG_API_KEY
const { data, meta } = await ud.projections({ league: 'NBA', view: 'compact', limit: 20 });
console.log(data.length, 'lines, observed', meta.observed_at);
```

javascript · every move, page by page

```
for await (const c of ud.pages('/api/v1/changes', { league: 'NFL', event_type: 'line.moved', limit: 200 })) {
  console.log(c.observed_at, c.player_name, c.stat, c.previous_line, '->', c.line);
}
```

## MCP server package (stdio)

For MCP clients that only speak stdio, or to keep the key in a local environment variable. The hosted server needs no install. [npm](https://www.npmjs.com/package/underdog-api-mcp) · [source](https://github.com/underdogapi/underdogapi-mcp) · [hosted server](https://underdogapi.com/mcp)

Claude Code

```
claude mcp add underdog -e UNDERDOG_API_KEY=ud_... -- npx -y underdog-api-mcp
```

Claude Desktop, Cursor, Windsurf (JSON config)

```
{
  "mcpServers": {
    "underdog": {
      "command": "npx",
      "args": [
        "-y",
        "underdog-api-mcp"
      ],
      "env": {
        "UNDERDOG_API_KEY": "ud_..."
      }
    }
  }
}
```

## Questions

Is there an official Underdog API Python package?

Yes: pip install underdog-api, then from underdog_api import Client. It is published on PyPI (https://pypi.org/project/underdog-api/) with source at https://github.com/underdogapi/underdogapi-python. Underdog Fantasy itself publishes no developer package; this client is for Underdog API, an independent service.

Is there an npm package?

Yes: npm install underdog-api for the JavaScript/TypeScript client (https://www.npmjs.com/package/underdog-api) and underdog-api-mcp for the stdio MCP server (https://www.npmjs.com/package/underdog-api-mcp).

Do I need an SDK?

No. Every endpoint is plain HTTPS with a bearer key, so requests, fetch or curl work too. The clients add paging, retries on per-minute limits and typed plan-limit errors.

Which MCP option should I use?

The hosted server at https://underdogapi.com/api/mcp needs no install. Use npx -y underdog-api-mcp when your client only speaks stdio or you want the key kept in a local environment variable.

What happens on the free key when I ask for graded results?

The clients raise PlanLimitError with the upgrade link and a few labelled sample rows; no credits are charged for it.

[Reference **API documentation** *Every endpoint and field.*](https://underdogapi.com/docs) [Agents **Underdog MCP server** *Hosted server and configs.*](https://underdogapi.com/mcp) [Python **Underdog API in Python** *requests, pandas, CSV.*](https://underdogapi.com/underdog-api-python) [Plans **Pricing** *Free key, then credits.*](https://underdogapi.com/pricing)

Underdog API is an independent data service. It is not affiliated with, endorsed by or operated by Underdog Fantasy or any company named on this page.

## References

- [GitHub: underdogapi](https://github.com/underdogapi)
- [PyPI: underdog-api](https://pypi.org/project/underdog-api/)
- [Source: underdogapi/underdogapi-python](https://github.com/underdogapi/underdogapi-python)
- [npm: underdog-api](https://www.npmjs.com/package/underdog-api)
- [Source: underdogapi/underdogapi-js](https://github.com/underdogapi/underdogapi-js)
- [npm: underdog-api-mcp (MCP)](https://www.npmjs.com/package/underdog-api-mcp)
- [Source: underdogapi/underdogapi-mcp](https://github.com/underdogapi/underdogapi-mcp)
- [Underdog API reference](https://underdogapi.com/docs)

## FAQ

### Is there a free Underdog API?

Yes. The Free plan is a real API key on the live board, not a sample: 100 credits a month, every league, separate Higher/Lower prices and the last 24 hours of line history. No card is needed.

### Is this the official Underdog Fantasy API?

No. Underdog API is an independent data service. It is not affiliated with, endorsed by or sponsored by Underdog Fantasy or Underdog Sports.

### What data does it return?

Underdog Higher/Lower lines with separate payout multipliers and availability for each side, stable market ids through line moves, alternate rungs, recorded line history, changes, graded results and coverage/status endpoints.

### How do I use it from Claude or another AI agent?

Connect the MCP server at https://underdogapi.com/api/mcp with a bearer key, or call the REST API. Agents can request a key for their user with POST /api/v1/agent/signup.

### How much does it cost after the free tier?

Developer is $49/month for 10,000 credits, Production $149/month for 50,000, Scale $499/month for 250,000. Errors and unchanged 304 responses cost zero credits.

### How fresh is the data?

Each row carries its observation time. Check /api/v1/status and /api/v1/coverage before relying on a sport or window; missing collection is reported as unavailable, never filled in.

### Does it place entries or give picks?

No. It is data only: no entries, account operations, guaranteed outcomes or betting advice.

---
Independent data service, not affiliated with Underdog Fantasy or Underdog Sports. Docs: https://underdogapi.com/docs · OpenAPI: https://underdogapi.com/openapi.json · llms.txt: https://underdogapi.com/llms.txt
