Settlements

Submit saved selections to grade them against ParlayLedger’s stored event results and player stats. Poll the same endpoint for updated grades. Your application owns wagers, parlay calculations, balances and payouts.

Every request needs your API key in the X-API-Key header and counts as one call against your monthly quota. See Authentication and Quotas and limits.

Endpoint	What it returns
POST /settlements/grade	Grade selections

Grade selections

POSThttps://api.parlayledger.com/settlements/grade

Send 1–50 selections as JSON. A successful batch counts as one API call, regardless of selection count. Example IDs and scores below are illustrative; use an actual Ledger event ID.

Auth X-API-Key header
Quota 1 call per request

Note:

One result per selection

HTTP 200 does not mean every selection was graded. Inspect each result’s status. Invalid items can appear alongside valid items; only status graded has an outcome.

JSON body

selectionsarrayrequired
1–50 selection objects. Results echo each clientReference.
selections[].clientReferencestringrequired
Your reference, unique within this batch. It correlates the response; it is not the identity of a stored bet.
selections[].eventIdUUIDrequired
Canonical ParlayLedger event ID. Resolve provider references with GET /stats/events/resolve/by-ref?provider=...&externalId=... first. Grading never guesses or creates events.
selections[].marketKeystringrequired
h2h, spreads, totals, or a supported player market listed below.
selections[].rulesetstringrequired
Must be safeparlay-v1. This is a named grading policy available to API clients.
selections[].periodstringoptional
Only full_game is supported; omission also means full game.
selections[].selection.sidestringrequired
h2h: home/away (draw for MLS only). Spreads: home/away. Totals and numeric props: over/under. Binary props: yes/no.
selections[].selection.linedecimal stringoptional
Required for spreads, totals and numeric props. Use the signed handicap for the selected team, e.g. "-3.5". Only integer and half-point lines are supported.
selections[].selection.teamNamestringoptional
Verifies the home/away team identity for team selections; can disambiguate a player prop.
selections[].selection.playerNamestringoptional
For props, provide a player name or both playerId and playerProvider. Ambiguous identities are not graded.
selections[].selection.playerIdstringoptional
Provider player ID. Must be accompanied by playerProvider.
selections[].selection.playerProviderstringoptional
Provider namespace for playerId, matching the stored player stats.

Request

curl -X POST "https://api.parlayledger.com/settlements/grade" \
  -H "X-API-Key: $PARLAYLEDGER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "selections": [
    {
      "clientReference": "bet-123",
      "eventId": "9e4244ef-70dc-4a28-a7ac-842644a105ff",
      "marketKey": "spreads",
      "ruleset": "safeparlay-v1",
      "period": "full_game",
      "selection": {
        "side": "home",
        "teamName": "Boston Celtics",
        "line": "-3.5"
      }
    }
  ]
}'

Response 200 application/json

200 OK

{
  "results": [
    {
      "clientReference": "bet-123",
      "eventId": "9e4244ef-70dc-4a28-a7ac-842644a105ff",
      "ruleset": "safeparlay-v1",
      "status": "graded",
      "outcome": "win",
      "reason": "final_score_against_line",
      "evidence": {
        "eventStatus": "final",
        "league": "NBA",
        "homeTeamName": "Boston Celtics",
        "awayTeamName": "New York Knicks",
        "homeScore": 107,
        "awayScore": 100,
        "line": -3.5
      },
      "settlementId": "19b3b4f4-8e4f-4d24-8fa3-b3555b145cb9",
      "revision": 1,
      "gradedAt": "2026-10-19T12:00:00.000Z"
    }
  ]
}

Errors

400Malformed batch, missing or duplicate clientReference, or selection count outside 1–50
500Infrastructure failure; retry the request with backoff
401Valid X-API-Key required
429Monthly API quota exceeded

Results and polling

Status	Meaning	Client action
`graded`	Outcome is `win`, `loss`, `push` or `void`.	Apply the outcome once for each of your bets and record the revision.
`pending`	Result or required player stats are not yet available.	Poll again later. Do not infer a push, zero stat or void.
`unresolved`	Identity, source data or regulation result cannot be safely determined.	Inspect reason and evidence; reconcile ambiguity before applying a grade.
`unsupported`	The league, market or line is outside supported coverage.	Route to your review process; repeated polling alone will not add support.
`invalid`	The selection fails validation, including an unsupported ruleset or period.	Correct the request using the returned reason.

Every result includes clientReference, status, reason and evidence. Valid selections also return eventId, ruleset, settlementId, revision and gradedAt. Malformed items may omit those fields. Evidence varies by market and can include final scores, player stats or the reason data is insufficient.

Store the canonical event ID and original market, side, line, player identity and ruleset when accepting a selection. Find event IDs through the Events API or provider reference lookup.
From your backend, periodically batch outstanding selections and POST them again to /settlements/grade. A five-minute polling interval is a reasonable starting point; adjust for your quota and sport schedule.
Match responses by clientReference. Apply only graded outcomes, with an idempotency record per client bet, settlement ID and revision.
Recheck recently graded selections to detect corrections. If an already applied result changes, reconcile it explicitly before updating balances or paying again.

Grades are scoped to your account and normalized selection. Repeating an unchanged selection returns the same settlement ID and revision, even with a different clientReference. A change in status, outcome or evidence increments the revision. gradedAt is the creation time of that revision, including pending revisions; it does not by itself mean the result is final.

Retry infrastructure failures with backoff. Earlier items in a failed batch may already have been saved, but resubmitting the batch is safe. There is no settlement GET route, webhook or automatic payout. Grading reads stored data and does not trigger an upstream refresh.

Supported markets

Main markets use h2h (moneyline), spreads and totals. Coverage is limited to the leagues below and depends on available stored results.

League	Main markets	Player market keys
NBA, WNBA, NCAAB	h2h, spreads, totals	`player_points`, `player_assists`, `player_rebounds`, `player_frees_attempts` (free throw attempts), `player_blocks`, `player_steals`, `player_field_goals`, `player_three_pointers`
NFL	h2h, spreads, totals	`player_pass_yds`, `player_pass_tds`, `player_pass_attempts`, `player_rush_yds`, `player_rush_attempts`, `player_reception_yds`, `player_receptions`, `player_kicking_points`
NCAAF, MLB	h2h, spreads, totals	Not supported
NHL	h2h, spreads, totals	`player_points`, `player_assists`, `player_goals`, `player_shots_on_goal`, `player_blocked_shots`, `player_power_play_points`, `player_total_saves`; each also supports its `_alternate` key.
MLS	Three-way h2h, spreads, totals	Numeric: `player_assists`, `player_shots_on_target`, `player_shots`. Binary yes/no: `player_goal_scorer_anytime`, `player_to_receive_card`, `player_to_receive_red_card`.
MMA, BOXING	h2h only	Not supported

For a numeric prop, for example, use marketKey: "player_points" with selection: { "side": "over", "line": "24.5", "playerName": "Jayson Tatum" }. For an MLS binary prop, use a supported binary market with side: "yes" or "no" and player identity; no line is required.

Grading rules

safeparlay-v1 uses final stored scores for supported non-soccer main markets. It does not promise to reproduce every bookmaker’s grading rules.

MLS requires verified regulation full time (FT). Extra-time, penalty and unverified regulation results remain unresolved. A draw loses a home/away three-way moneyline selection and wins a draw selection. Other supported tied moneylines push.
Supported cancelled events void. Postponed events normally remain pending. Under this ruleset, MMA/boxing moneylines with no final result 72 hours after the scheduled start void unless the fight is currently live.
Missing players, missing stat fields and unknown participation remain pending. Missing stats are never treated as zero, and absence does not imply a DNP void.
Ambiguous player identities, conflicting player stats and events mapped to multiple distinct events from the same provider remain unresolved. A supplied teamName that conflicts with the selected home/away team also remains unresolved.
Quarter lines, partial-game markets, first/last scorer, tennis and unlisted leagues or props are not graded.