Grading¶
Product id: grading
Our verdict on every selection of our own lines (book: null) in live, pregame and props: win, lose, push,
half_win, half_lose or void, by our published grading rules. It is
for a client that wants to settle the way we do. A client with its own rules takes the
scoresheet from Scores instead.
grading is an add-on: a key has it together with live, pregame or props (one or more),
and receives the verdicts on those products only. Futures are not graded.
The grading object¶
One grading holds our verdicts on one product of lines for one game. A game graded in pregame
and in props has two gradings, one for each. Complete example.
| Field | What it is |
|---|---|
eventId, product, sport, league |
The game, and the product of lines graded: live, pregame or props |
basis |
The revision of the game's scoresheet the verdicts were reached on |
rules |
The version of our rules applied: 2026-11 |
markets |
{marketId, selections: [{selectionId, outcome, deadHeatFactor}]}, with the ids of that product's lines |
held |
{marketId, selectionId, reason}: the selections without a verdict yet, and why |
complete |
true when every selection we grade has its verdict: nothing held, nothing left out. Markets we leave out without a verdict (see What a grading covers) do not count: true says nothing about them |
revision |
Grows with every change, and may skip numbers. A higher one replaces a lower one |
corrected |
true when a verdict published before changed or was withdrawn: check anything you settled on it. It stays true in later revisions |
updatedAt |
When this revision was published: what updatedSince filters on |
Outcomes¶
| Outcome | Pays |
|---|---|
win |
Stake × price |
lose |
Nothing |
push |
The stake back |
half_win |
Half the stake wins at the price, half comes back (quarter lines) |
half_lose |
Half the stake is lost, half comes back (quarter lines) |
void |
The stake back |
deadHeatFactor is the share of the stake that stands when a dead heat applies. It is null
otherwise, and today always: no market type we grade applies one.
Matching a verdict to a bet¶
- Match on two keys: the grading's
productand theselectionId.product(the field of the grading, not of the stream message) must be the product you took the line from:live,pregameorprops;selectionIdis thesel_you received with it. Never match on thesel_alone: a market can carry the samemkt_, and a selection the samesel_, inliveand before the game, and the verdict of each product follows its own rules (some differ between bets taken before the game and in play). Within one product, aselectionIdnames one bet only. - The message and the grading say different things. On the stream, the envelope's
productisgrading(the stream the message belongs to); the grading's ownproduct, insidedata, is the product of lines it grades. - A market that left the board is graded all the same. A grading is built from what the game
offered, not from what is on the board now: a market removed before the game ended, or a game
that already left the board, still gets its verdicts. Every selection you received, of a type
and period listed in
gradedPeriodsBySport, gets a verdict or aheldentry; if one cannot be given, the grading iscomplete: false. - One grading per product.
pregamehas the verdicts on the main lines,propson the rest. Each iscompleteon its own.
What a grading covers¶
Where we commit to a verdict is in the catalog: Where we grade. For each market of a game, one of these applies:
| Case | In the grading |
|---|---|
Its type and period are listed in gradedPeriodsBySport for the sport |
A verdict in markets, or an entry in held with its reason |
| Its type is graded nowhere (futures, for example) | Never appears, in markets or in held |
A sportsbook's market (book is not null) |
Never appears, in markets or in held, and does not count for complete: we do not grade the books' lines |
| Its type is listed, but the league's results do not carry what it needs (period scores, match statistics, the goal timeline) | Usually no verdict and no held entry; a whole-game market read on the periods (half time/full time, win both halves) is held with market_not_graded |
| A player's figure for one half, quarter or period | Held with period_stats_unavailable |
| Not listed for the sport or period, but offered | No commitment: it may get a verdict, be held, or not appear |
Selections held with period_stats_unavailable or market_not_graded stay held: we never give
them a verdict or void. Settle them yourself from the scoresheet.
When verdicts come¶
Only from confirmed scoresheets. While a game's scoresheet is provisional or disputed,
every selection of the game is in held with awaiting_second_source or sources_disagree. A
game whose scoresheet is never confirmed (in a league only one source covers, the second source
never comes) gets no verdicts at all: its selections stay held, and are yours to settle.
A verdict can also wait for facts that come later than the score: the boxscore, the timeline,
the lineups. A new revision can move a selection from held to markets; that is not a
correction.
Held selections end. On a game confirmed as played out (finished), a selection still held
when the re-checks of the game are over (from 24 hours after it, usually within 60) is given
void in a new revision, except one held for period_stats_unavailable or market_not_graded,
which stays held: we do not grade it, you do. On a game that ended otherwise (abandoned, retired,
incomplete), held selections stay held. The re-checks end at the latest about 60 hours after the
game: no revision comes after that.
Held reasons¶
| Reason | Why there is no verdict yet |
|---|---|
awaiting_second_source |
The scoresheet is provisional: one source so far |
sources_disagree |
The scoresheet is disputed |
regulation_unknown |
Soccer: no record says whether the game went past ninety minutes |
props_on_hold |
The boxscore is late, or a second one disagrees: the player props wait for a while |
no_boxscore |
No boxscore for the game yet |
player_not_in_boxscore |
The player is not in the boxscore |
stat_unavailable |
The boxscore does not give the statistic |
line_unreadable |
The market's line could not be read |
timeline_unavailable |
The market needs the goal timeline, and there is none |
period_score_missing |
The market needs the score of a period, and there is none |
match_stats_missing |
The market needs a match statistic (corners, cards…), and there is none |
period_stats_unavailable |
A player's figure for one half, quarter or period: no boxscore gives one. Stays held |
market_not_graded |
We do not grade this market here: in this league (its results lack what the market needs), or in this sport since a change to what we grade made after the market was offered. Stays held |
participation_unknown |
Soccer: the lineups do not tell whether the player played or, for a card bet made before the game, whether he started |
record_unclear |
A soccer player's cards: we cannot tell whether a booking was his, or the bookings do not add up to the team's count |
ungraded |
Any other reason |
New reasons may be added; treat one you do not know as ungraded.
Getting verdicts¶
- Stream:
products=grading, optionally withgradingProducts=live,pregame,props(by default, every product of lines your key includes) and thesports,leaguesandeventsfilters. Agradingmessage carries the whole grading: replace what you had for that game and product. - REST:
GET /v1/{product}/grading/{eventId}for one game, andGET /v1/{product}/grading?updatedSince=…for every grading revised since then, where{product}islive,pregameorprops. GET /v1/events/{eventId}lists, undergrading, a link per product that has verdicts on the game.
The snapshot of grading on the stream holds no games. After a fresh snapshot, catch up with
GET /v1/{product}/grading?updatedSince=…. A resume with since replays the last 5 000 grading
messages; from further back you get a snapshot, and catch up the same way.
Verdicts are kept 7 days after their last revision (scoresheets, 30).
Our rules¶
The rules we grade by are versioned (rules); a change to any of them is a new version,
announced in the changelog. The full set is in Grading
rules. In short:
- Facts: the result as it stands when the game ends, confirmed by at least two independent sources that agree.
- Not played: every selection
void. Interrupted: no verdict while the game can still resume. Abandoned: graded on the score when play stopped if it had gone far enough (soccer, for example, from five minutes before its end); otherwisevoid, except what the score had already settled and the sets already completed. - Periods: soccer's whole match and second half are regular time only; basketball, American football, ice hockey and baseball include overtime, the shoot-out and extra innings in the whole game.
- Player props: a player who did not take part is
void; for his figures we grade only the whole game. - Lines: a whole-number line landed on is a
push; quarter lines split the stake in two halves.