# Provisional grading with retained contracts and result revisions Assess actual retained offer snapshots against verified event scores, with customer-scoped idempotency and explicit separation from official sportsbook settlement. Canonical page: https://getoddsapi.com/docs/settlement-assessments ## 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 ## Pricing | Plan | Allowance | Price | | --- | --- | --- | | Free key | 1,000 requests a day, 60 a minute | $0, no card | | Developer Bundle | 10,000 requests or credits a month on each of four sources | $149 a month | Free development allowance: 1,000 requests per UTC day and 60 per minute per account, with no payment step. Paid: the Developer Bundle at $149 per month, with 10,000 monthly requests or credits on each of four sources. Details: https://getoddsapi.com/bundle ## Guide Canonical: https://getoddsapi.com/docs/settlement-assessments Reviewed: 2026-11-07 UTC Assess actual retained offer snapshots against verified event scores, with customer-scoped idempotency and explicit separation from official sportsbook settlement. ## Assess the contract you actually observed POST /api/v1/settlements/grade accepts one retained event_id and1–50 selections. Each selection requires offer_id and may include history_seq for an exact retained seven-day history snapshot. Without history_seq the current stored offer line is used; this is not a record of the line on your actual wager. The bearer key must grant DraftKings, and DraftKings must be selected in the account before price-contract retrieval. A successful request costs one credit. Only stored contracts and verified provider scores are accepted: the body cannot supply scores, settlement outcomes, arbitrary lines or custom rules. ```bash curl --fail-with-body -X POST "https://getoddsapi.com/api/v1/settlements/grade" -H "Authorization: Bearer $GETODDS_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: example-assessment-1" --data '{"event_id":"espn-draftkings:espn:NFL:401873028","selections":[{"offer_id":"RETAINED_OFFER_ID"}]}' ``` ## Understand the deliberately narrow policy completed-game-score-v1 supports NFL, NBA, NCAAF and NCAAB full-game moneyline, spread and total contracts. Spread and total lines must be integers or half points. A positive score margin is won, a negative margin lost, and an equal margin a computed push. All reported final score points are counted, including overtime if present in that score. These are provisional arithmetic assessments. Book-specific overtime, cancellation, abandonment, special-market and void rules are not verified by this policy. Every row keeps official_outcome=unknown and official_settlement_verified=false. There is no payout or bankroll operation. Pre/in events return pending. Nonstandard final statuses, unsupported sport/period/side/quarter lines, absent contracts or incomplete final evidence are ungradeable. Provider failures return an error and never become fabricated voids. ## Retry safely and observe later revisions Idempotency-Key is required and scoped to the customer account. Repeating it with the same normalized body returns the same stored assessment, even if a provider result subsequently changes. Using it with a different body returns409 IDEMPOTENCY_CONFLICT. Every successful retry still consumes one request and one credit. To reassess after a later provider update, use a new key. Different observed result payloads produce append-only revisions with supersedes references. Identical observations reuse the revision. A return to a prior score still creates a new revision. Older network receipts cannot overwrite a newer different observation. evidence_observed_at is the referenced revision’s first receipt; assessment_observed_at is the receipt used for the assessment, which can be newer with unchanged scores. A separate latest-observation watermark advances even when a revision is reused. Neither clock is a verified provider correction timestamp. This ledger begins with successful grading requests; it is not complete historical correction coverage. ## Read evidence without mistaking it for official settlement GET /api/v1/settlements?event_id=... returns captured provider-result revisions, newest first, and official_settlements=[] with official_status=unverified. DraftKings source access is required; price selection is not required because this read does not expose offer prices. Empty evidence means no captured observation, not an inferred event result. Native FanDuel outright prices currently have no verified outcome/void/correction payload or verified mapping to tournament athlete results. An unrelated leaderboard is not substituted for settlement of those markets. Official market adjudication remains a separate source dependency. ## Questions ### Is won an official bookmaker decision? No. It is the stated arithmetic policy applied to a retained contract and verified event evidence; official_outcome remains unknown. ### Will retries silently change my grade? No. The same customer idempotency key freezes the original assessment. A new key may observe a newer revision. ### Can missing box scores or disappeared markets create voids? No. Missing evidence stays unavailable or ungradeable, never an official void. ## Sources - [GetOdds API contract](https://getoddsapi.com/openapi.json) - [Verified provider event results](https://getoddsapi.com/docs/event-results) - [FanDuel NJ house rules and resettlement terms](https://policies.fanduel.com/SB/NJ/2026-10-15T12-42-58.html) Independent product; not affiliated with the operators named. No picks or predicted profits. --- GetOdds is an independent developer product and is not affiliated with any sportsbook or pick’em operator. Prices describe data, not betting advice.