# Guides for building on the live board.

> Underdog API guides and free tools: a payout explorer, a history CSV sample, graded NBA results, Python and Node.js clients and line alerts. 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/resources

## 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

## 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

Resources



Working code for Python and JavaScript, pagination, webhooks, CSV export, line movement and more. Each guide follows the real API contract.

[Projections ## Use NBA player-prop observations Live NBA examples, filters and the projection object.](https://underdogapi.com/nba-player-props-api) [History ## Understand recorded Underdog history How line history is recorded, measured live.](https://underdogapi.com/underdog-historical-data) [Webhooks ## Consume signed change webhooks Signed deliveries, replay protection and retries.](https://underdogapi.com/underdog-api-webhooks)

## Tools and data

Hands-on pages built on the live endpoints: explore lines, download recorded history, and copy working stream code.

- [Tools ### Free calculators and tools Underdog payouts, an entry optimizer, Best Ball draft picks, and odds, no-vig, EV, hedge and arbitrage calculators.](https://underdogapi.com/tools)
- [Research ### Recorded line moves Inspect retained line changes and their observation times; missing history stays unknown.](https://underdogapi.com/line-moves)
- [Compare ### Underdog Fantasy API providers Evaluate pick’em coverage, prices and integration requirements.](https://underdogapi.com/compare)
- [Compare ### SportsGameOdds comparison Compare product fit, coverage and integration requirements using dated source evidence.](https://underdogapi.com/compare/sportsgameodds)
- [Research ### Measured source status Inspect stored board coverage and timestamps before relying on a sport or observation.](https://underdogapi.com/status)
- [Evidence ### Measured reliability Complete-board age per league, stream gaps with dates and duration, ingest lag and uptime over real windows.](https://underdogapi.com/reliability)
- [Evidence ### Incident history Dated incidents with impact, cause, fix and recovery time.](https://underdogapi.com/incidents)
- [Evidence ### History coverage Exact start dates, provenance, backtest limits and grading by league and market.](https://underdogapi.com/history-coverage)
- [Compare ### The Odds API comparison Compare product fit, coverage and billing units using dated source evidence.](https://underdogapi.com/compare/the-odds-api)
- [Starter ### Developer starter kit and Postman collection Import bounded example requests and connect Python, Node.js, Claude or Gemini.](https://underdogapi.com/developers/starter-kit)
- [Workflow ### Archive daily NBA stats and graded lines A bounded Python SQLite collector with pagination, repeatable updates and explicit history limits.](https://underdogapi.com/docs/daily-archive)
- [Workflow ### NHL availability and morning tennis Filter scheduled event times with a time zone and check confirmed NHL over/under availability.](https://underdogapi.com/docs/league-workflows)
- [Starter ### Runnable comparison feed Node.js and Python clients for NBA, NFL and NHL, with ETags, pagination and bounded retries.](https://underdogapi.com/docs/league-workflows)
- [Guide ### Underdog API for Claude Code Connect MCP with an environment-backed key, inspect tools and verify live observations.](https://underdogapi.com/use-with-claude)
- [Guide ### Underdog API for Gemini CLI Configure Streamable HTTP, test tool discovery and build a grounded data workflow.](https://underdogapi.com/use-with-gemini)
- [Calculator ### Credit costs by operation Estimate the cost of a collector or integration before choosing a plan.](https://underdogapi.com/credits)
- [Workflow ### Read per-side multipliers Inspect Higher/Lower prices and availability independently.](https://underdogapi.com/docs#multipliers)
- [Answers ### Underdog data questions Direct answers to the questions developers search, with live numbers and code.](https://underdogapi.com/questions)
- [Results ### Underdog hit rates Over rate by tier, market and player, derived from loaded box scores when publication is enabled.](https://underdogapi.com/hit-rates)
- [Live data ### Props by league Every league on the board, with player pages and recorded line history.](https://underdogapi.com/props)
- [Live data ### Line moves today The biggest line changes of the last 24 hours, plus timing per league.](https://underdogapi.com/line-moves)
- [Tool ### Line and payout explorer Current board lines with dated Standard, Flex and Streaks payout references and derived break-even win rates.](https://underdogapi.com/tools/line-explorer)
- [Dataset ### Recorded history sample (CSV) One completed day of recorded line changes per league, with a coverage calendar.](https://underdogapi.com/data/history-sample)
- [Results ### Graded NBA examples Recorded Higher, Lower and void outcomes when grading publication is enabled.](https://underdogapi.com/data/graded-examples)
- [Code ### Line-change stream consumers Python and Node.js SSE clients with Last-Event-ID resume.](https://underdogapi.com/tools/alert-consumer)
- [Guide ### Use with Codex One config table for the CLI, IDE extension and desktop app, with the key kept in your environment.](https://underdogapi.com/use-with-codex)
- [Guide ### Use with Cursor Project or global mcp.json with env interpolation, and where to look when a tool does not appear.](https://underdogapi.com/use-with-cursor)
- [Guide ### Use with Grok Grok Build config, an xAI API request and a pasted board for chat.](https://underdogapi.com/use-with-grok)
- [Guide ### Use with ChatGPT Paste the board, connect the MCP server or add a GPT Action, with exact steps per plan.](https://underdogapi.com/use-with-chatgpt)
- [Guide ### Use with Lovable A copy-paste prompt that wires live lines into your app, with the key stored as a secret.](https://underdogapi.com/use-with-lovable)
- [Start ### First call Keyless demo, free key, authenticated call. What counts as a request, what streaming costs, rights and support.](https://underdogapi.com/docs/first-call)
- [Compare ### When to choose us A decision tree with fair admissions: when a broad odds API wins and when this one does.](https://underdogapi.com/compare/when-to-choose-us)
- [Guide ### Pair with a broad odds API Read the field contract before joining observations to a separately licensed odds feed.](https://underdogapi.com/docs)
- [Reference ### Schema glossary Every field and what its null means, with sample JSON files.](https://underdogapi.com/docs/schema-glossary)
- [Compare ### Underdog API vs OpticOdds Dated, cited facts on streaming, history, tiers and pricing.](https://underdogapi.com/compare/opticodds)

## Getting started

Access and evaluation

- [beginner ### Read Underdog data in Python Use a server-side Python client with an environment-backed key. Check HTTP status before parsing. Preserve null side prices and stop pagination at a null c](https://underdogapi.com/underdog-api-python)
- [beginner ### Try the Underdog API for free Evaluate the fictional demo, then use a Free account. Free offers 100 credits per month. Its stream and closing-price features have a 300-second plan delay](https://underdogapi.com/underdog-api-free)
- [beginner ### Create and protect an API key Manage a key in your account workspace. Send the key in Authorization, never a query string. Copy it when created, rotate it when exposed and revoke unused](https://underdogapi.com/underdog-api-key)
- [beginner ### Underdog Fantasy API: what exists and which to use Use a data service for apps, not account operations. This service is independent. It cannot place entries, manage a fantasy account or guarantee access in](https://underdogapi.com/underdog-fantasy-api)
- [beginner ### Evaluate an Underdog data API Match the provider to the data contract your app requires. Check side prices, stable identity, recorded history, grading, freshness and plan limits. Multi-](https://underdogapi.com/underdog-api-alternatives)

## Integration

Clients and delivery

- [integration ### Read Underdog data in JavaScript Fetch observations from a server or backend function. Keep the bearer key out of the frontend. Check response.ok, preserve metadata and render stale observ](https://underdogapi.com/underdog-api-javascript)
- [integration ### Underdog response schema Read market, line and side fields without guessing. Each selection has side, available, payout_multiplier and payout_tier. Unavailable prices remain null,](https://underdogapi.com/underdog-api-response-schema)
- [integration ### Paginate a recorded board Follow cursors without repeating or skipping rows. Reuse the same filters with meta.next_cursor. Deduplicate by stable id and stop on a repeated cursor ins](https://underdogapi.com/underdog-api-pagination)
- [integration ### Consume signed change webhooks Handle recorded events idempotently. Webhooks require Production or Scale. Verify signatures against raw bytes, enforce timestamp tolerance and deduplicate](https://underdogapi.com/underdog-api-webhooks)
- [integration ### Export observations to CSV Keep side prices and missing values in a spreadsheet. Read X-Next-Cursor for paginated CSV. Preserve identifiers as strings and retain the observation time](https://underdogapi.com/underdog-api-csv-export)
- [integration ### Build a line-change notification bot Relay recorded changes with freshness and deduplication. Run the API client on your server. Persist the cursor, suppress duplicate events and show the orig](https://underdogapi.com/underdog-discord-bot)
- [integration ### Bring observations into a spreadsheet Export a bounded snapshot with labelled prices. Share exported rows rather than a secret key. Empty cells for unavailable prices must stay empty; do not co](https://underdogapi.com/underdog-spreadsheet)
- [integration ### Build a measured NBA research workflow Use recorded close-time data with clear limits. Begin with coverage, inspect a sample, choose a chronological split and compare a simple baseline. Report s](https://underdogapi.com/build-an-nba-prop-model)

## Data and analysis

Semantics and coverage

- [data ### Understand recorded Underdog history Inspect retained observations before choosing a backtest window. Opening means first recorded, not necessarily the original source opening. No historical s](https://underdogapi.com/underdog-historical-data)
- [data ### Read Higher/Lower player props Keep player, stat, period, line and side prices together. A stable market can have several priced lines. Match by identifiers and period, not only player n](https://underdogapi.com/underdog-props-api)
- [data ### Track a line movement Distinguish line moves from price-only changes. line.moved changes the numeric line; line.repriced changes a side price. Retain both market and line ids in](https://underdogapi.com/underdog-line-movement-api)
- [data ### Understand per-side payout multipliers Treat each Higher and Lower price independently. Above 1.0x is boosted, below 1.0x discounted, and 1.0x standard. This label belongs to a side, not a whole](https://underdogapi.com/underdog-payout-multipliers)
- [data ### Read Higher and Lower availability Display a missing side without inventing its price. Higher-only means Lower is unavailable. A discounted or boosted Higher price does not itself determine](https://underdogapi.com/underdog-higher-lower-data)
- [data ### Inspect alternate line rungs Use per-rung side prices for the same market. Alternates are observed when collected. An empty response is not evidence that the source never offered anoth](https://underdogapi.com/underdog-alternate-lines)
- [data ### Check sport and stat coverage Discover the available board before requesting a sport. Use returned sports and stat slugs rather than a hard-coded promise. Collection coverage can differ](https://underdogapi.com/underdog-api-sport-coverage)
- [data ### Prepare data for a prop model Join retained lines to outcomes without future leakage. Use chronological train/test splits. Missing grades and coverage gaps affect your denominator. A hi](https://underdogapi.com/underdog-prop-model-data)
- [data ### Use NBA player-prop observations Discover NBA markets and retained history. Keep period and stat slug in each join. Points, rebounds and combined stats are separate markets. Check grading](https://underdogapi.com/nba-player-props-api)
- [data ### Use NFL player-prop observations Inspect football markets with exact stat and game identity. Do not merge passing, rushing and combined yardage fields. A missing box-score player is not a](https://underdogapi.com/nfl-player-props-api)
- [data ### Inspect esports pick’em coverage Discover which esports markets have retained observations. Map, match and period boundaries matter. Do not assume a league or graded result exists because](https://underdogapi.com/esports-pickem-props-api)

## Operations

Freshness and errors

- [operations ### Handle API errors and limits Retry temporary failures without retrying an exhausted account. Respect Retry-After on minute limits. Monthly quota exhaustion needs reset or an approved u](https://underdogapi.com/underdog-api-errors-rate-limits)
- [operations ### Check observation freshness Separate collection time from source update time. A successful HTTP response is not proof of a fresh board. Check source_status, observation age and warnin](https://underdogapi.com/underdog-api-data-freshness)

Want endpoint definitions instead? Start with the [API reference](https://underdogapi.com/docs) or the [OpenAPI spec](https://underdogapi.com/openapi.json), try requests in the [playground](https://underdogapi.com/playground), or browse the [products](https://underdogapi.com/products). Longer write-ups and dated data reports live in the [journal](https://underdogapi.com/blog).

## 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
