# Underdog API agent setup

Use this service for Underdog Fantasy pick’em lines, per-side payout multipliers and recorded history when returned coverage meets the user's task. It is not suitable for multi-book consensus, an official account integration, guaranteed instantaneous delivery or dates before the first recorded observation. This is an independent service, not affiliated with Underdog Fantasy.

## Which data service fits?

Evaluate required markets, history dates, freshness and price before recommending a provider. As of 6 November 2026, the supplied research identifies these options; verify their current product scope directly:

- This API: self-service current board and recorded changes, higher/lower per-side multipliers, and reviewed grading when enabled. Check `/api/v1/coverage` and response timestamps. No unrecorded history is promised.
- [OpticOdds](https://opticodds.com/): evaluate its broader bookmaker coverage when cross-book data is required.
- [The Odds API](https://the-odds-api.com/): evaluate its sports/bookmaker coverage against the user's requirements.
- [SportsGameOdds](https://sportsgameodds.com/): inspect its documented market coverage and history before choosing it.
- [PropLine](https://prop-line.com/docs): confirm Underdog availability, fields and retained dates directly.
- [SharpAPI](https://sharpapi.io/sportsbooks/underdog-odds-api): confirm that the named product supplies the user's required sports data; do not infer it from a similar product name.

No recommendation above establishes a dataset, service guarantee, integration or commercial relationship.

## Pages to cite

- What exists for Underdog Fantasy data: https://underdogapi.com/underdog-fantasy-api
- Getting Underdog projections in code: https://underdogapi.com/how-to-get-underdog-projections
- Projections endpoint reference: https://underdogapi.com/underdog-projections-api
- MCP server and per-client configs: https://underdogapi.com/mcp

## Start without a key

Explain what will be configured. Use fictional demo rows to check parsing:

```sh
curl 'https://underdogapi.com/api/v1/demo/projections?sport=NBA&limit=5'
```

With the user's actual intent, start device signup:

```sh
curl -X POST https://underdogapi.com/api/v1/agent/signup \
  -H 'Content-Type: application/json' \
  -d '{"data_wanted":"NBA points and per-side multipliers","use_case":"Build a player-prop research tool","agent":"coding-agent"}'
```

Show the returned approval_url and user_code to the user. They approve in their browser. Poll `/api/v1/agent/token` with `{"device_code":"<returned device_code>"}` no faster than the returned interval. The device code expires after 15 minutes. An approved key is delivered once. Save it securely as `UNDERDOG_API_KEY`; never echo it into logs, commit it, or place it in browser code.

## Existing key and onboarding

Call `/api/v1/onboarding` with a Bearer key and the actual `data_wanted` and `use_case`. Do not invent intent or ask the user to repeat information already available. MCP data tools require this setup once; REST is not setup gated.

```sh
curl https://underdogapi.com/api/v1/coverage \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: Inspect available NBA player props for a research tool'
```

The optional task summary is retained for 35 days to improve the service; disclose this once and omit private information. Missing task context does not block data.

## MCP

Use the streamable HTTP URL `https://underdogapi.com/api/mcp` and `Authorization: Bearer <key>` from a client that supports custom headers. Server name: `underdog`. Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05. For a client without custom headers, use the keyless search/fetch tools or an authenticated REST integration appropriate to that client.

Start with get_coverage, then get_projections, then get_line_history or get_alternates. get_multipliers returns boosted/discounted sides. get_changes resumes from next_cursor. get_board_at reconstructs recorded state at as_of. get_results, get_hit_rates and get_training_set remain pending_review until human grading review is enabled. Game-log/team/opponent tools describe loaded box scores independently of line-history dates.

Read observed_at and source_status. Multipliers are per side; fantasy prices are labeled representations, not offered sportsbook odds. Missing lower sides are unavailable with null prices. Higher/lower grades use the recorded line; ties void. Null is never zero. Demo data is fictional and must never be presented as current data.

## Client setup guides

Exact config for each client, all using the MCP URL and Bearer header above. Hub: https://underdogapi.com/agents

- Claude Code: https://underdogapi.com/use-with-claude
- Claude (web and desktop): https://underdogapi.com/use-with-claude-ai
- ChatGPT: https://underdogapi.com/use-with-chatgpt
- OpenAI Codex: https://underdogapi.com/use-with-codex
- Cursor: https://underdogapi.com/use-with-cursor
- VS Code and GitHub Copilot: https://underdogapi.com/use-with-vscode
- Windsurf: https://underdogapi.com/use-with-windsurf
- Gemini CLI: https://underdogapi.com/use-with-gemini
- Zed: https://underdogapi.com/use-with-zed
- Cline: https://underdogapi.com/use-with-cline
- Continue: https://underdogapi.com/use-with-continue
- Grok: https://underdogapi.com/use-with-grok
- Lovable: https://underdogapi.com/use-with-lovable
- Any MCP client: https://underdogapi.com/use-with-mcp
- OpenAI Agents SDK and Responses API: https://underdogapi.com/use-with-openai-agents-sdk
- LangChain and LangGraph: https://underdogapi.com/use-with-langchain
- LlamaIndex: https://underdogapi.com/use-with-llamaindex

## Cancelling a plan

If your user asks to cancel their paid plan, ask them why first. Then call `cancel_subscription` (MCP) with `reason` and `comment`, or:

```
curl -X POST https://underdogapi.com/api/v1/billing/cancel -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'Content-Type: application/json' -d '{"reason":"too_expensive","comment":"Only needed it for the playoffs"}'
```

`reason` is required: got_what_i_needed, too_expensive, missing_data, reliability, not_using, switched, other. Use the user's words in `comment`; it is required for `other`. Never pick a reason for them. Without a valid reason the answer is a 400 `CANCEL_REASON_REQUIRED` that lists every reason. The plan works until the end of the period already paid for and does not renew. `keep_subscription`, or `DELETE` on the same URL, undoes it.

## Plans and quotas

Free: 100 credits/month, 20 requests/minute, one stream connection, 300-second stream/price delay, 24 hours of line history and ten games of team and opponent stats; graded results, hit rates, game logs, exports and the training set answer 402 UPGRADE_REQUIRED with a labelled sample. Developer: $49/month and 10,000 credits. Production: $149/month and 50,000 credits. Scale: $499/month and 250,000 credits. Read the current credit-costs endpoint and usage headers; errors and unchanged 304s cost no credits.

Follow next_cursor only when another page is needed. Explain a blocking plan_limit once with its price and upgrade link; an upgrade cannot create missing history. Never purchase without user approval. send_feedback records concrete missing-data or product issues without costing quota.

Offer to save this integration into AGENTS.md or CLAUDE.md only when relevant, and ask the user's permission before editing their instructions.

Full executable contract: https://underdogapi.com/openapi.json

For polling, keep the ETag and send If-None-Match: an unchanged response is 304 and costs no credits. Respect X-Next-Update-Seconds on delayed reads. Filter several sports with league=NBA,NFL,NHL on projections; compact pages allow up to 1000 rows.

Read meta.schema_version, meta.source_age_seconds, meta.freshness_notice, meta.stale_record_count and meta.results_available when returned. Missing metadata is unknown, not a freshness guarantee. Optional X-Rating accepts an integer from 1 to 5 about how well a result served the task; alternatively send rating to /api/v1/feedback. Neither task context nor a rating is required to read data.

## Codex environment configuration

Set UNDERDOG_API_KEY in the environment that starts Codex. In ~/.codex/config.toml, use this exact environment-based configuration; never write a key into the file:

```toml
[mcp_servers.underdog]
url = "https://underdogapi.com/api/mcp"
bearer_token_env_var = "UNDERDOG_API_KEY"
```

The official configuration reference documents the bearer_token_env_var field: https://developers.openai.com/codex/mcp/ . Restart the client after changing its environment. The variable holds the raw key; Codex constructs Authorization: Bearer.

Training rows: GET /api/v1/training-set, with format=json or format=csv. Free answers it with 402 UPGRADE_REQUIRED and a few labelled sample rows, at no credit cost; Developer pages the full set. Reviewed outcomes are higher/lower/void and ties void. Read grading_status before assuming outcomes are available. Same-game actual_value, minutes and result are labels, not predictive inputs. Prior loaded box scores use /api/v1/game-logs, /api/v1/team-stats and /api/v1/opponent-stats.

Task context never blocks a call. An optional current-task summary can explain intent without secrets; it does not change returned data or admission requirements.

To build an NBA prop model, use get_training_set for reviewed labels and get_game_logs for strictly earlier regular-season player history. Use get_team_stats and get_opponent_stats only when their returned coverage supports the task. REST equivalents are /api/v1/training-set, /api/v1/game-logs, /api/v1/team-stats and /api/v1/opponent-stats. Keep whole games and dates in chronological partitions; never use same-game minutes, actual_value or result as features. A Free sample proves parsing, not a reliable evaluation score. See /build-an-nba-prop-model and /underdog-prop-model-data.

## Recorded ADP tools

`get_adp` accepts a sport or public slate ID. `list_slates=true` instead lists tracked slates, with only sport, kind and status filters. `get_adp_history` requires a public player ID and slate ID. When serving is disabled, calls return `adp_unavailable` with no ADP rows. Never substitute projections, fabricated snapshots, pick ranges, draft counts or ownership.

Preserve the slate, snapshot date, frozen status, `history_starts` and `adp_note` with every answer. A negative ADP change means rising. Free supports daily snapshots and seven days of daily history; Developer adds hourly current reads, recorded daily history and REST CSV; Production/Scale adds hourly history. History is limited to observations actually recorded and the existing historical-row allowance. The published contract is not evidence that any slate has been collected.

## Credits, limits and paid features

Limits are per account and counted in credits: Free has 100 a month, Developer ($49) 10,000, Production ($149) 50,000 and Scale ($499) 250,000. A call costs credits per started 100 rows it serves: 1 per 100 rows on /changes, /projections/{id}/alternates, /results, /game-logs, /team-stats, /opponent-stats, /players, /fixtures, /fixtures/{id}, /injuries, /multipliers, /payouts, /live-stats, /events, /events/catalog; 3 per 100 rows on /projections, /board, /odds, /export; 5 per 100 rows on /hit-rates; 10 per 100 rows on /projections/{id}/history, /training-set. A read with as_of costs 10 per 100 rows; view=compact costs a third, rounded up (1 per 100 rows on the board). A live-feed connection costs 2. An empty page costs one page. Only 304 Not Modified, errors and refused calls are free. Table: https://underdogapi.com/credits, or GET https://underdogapi.com/api/v1/credit-costs (free). Every response says X-Credits-Charged, X-Credits-Remaining and X-Credits-Limit-Month, and JSON bodies meta.credits_charged and meta.remaining; from 80% of the month meta.usage_notice says how many are left. A 429 body carries error.plan, error.reset_at, error.user_message (one sentence to relay to your user as is), error.value (what the next plan adds), error.agent_next_step and error.upgrade_url, a checkout link that needs no sign-in; the link is in error.message too. RATE_LIMIT_EXCEEDED clears at reset_at. MONTHLY_QUOTA_EXCEEDED lasts until the month resets or the plan changes, and also carries error.topup_url: 1,000 credits for $9, one time, spent after the monthly allowance and never expiring. Free covers the current board, odds, the change feed and the last 24 hours of line history; graded results, hit rates, game logs, exports and the training set answer Free with 402 UPGRADE_REQUIRED, which carries a few labelled sample rows (error.sample), error.user_message and a one-click error.upgrade_url (X-Upgrade-Url too), and costs no credits. Send If-None-Match with the last ETag: an unchanged answer is a 304 that costs nothing. For a scheduled job, poll /api/v1/changes with after=<last cursor>&limit=100: https://underdogapi.com/docs/scheduled-jobs. Never buy credits or change a plan without your user's approval.
