Skip to content

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 product and the selectionId. product (the field of the grading, not of the stream message) must be the product you took the line from: live, pregame or props; selectionId is the sel_ you received with it. Never match on the sel_ alone: a market can carry the same mkt_, and a selection the same sel_, in live and 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, a selectionId names one bet only.
  • The message and the grading say different things. On the stream, the envelope's product is grading (the stream the message belongs to); the grading's own product, inside data, 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 a held entry; if one cannot be given, the grading is complete: false.
  • One grading per product. pregame has the verdicts on the main lines, props on the rest. Each is complete on 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 with gradingProducts=live,pregame,props (by default, every product of lines your key includes) and the sports, leagues and events filters. A grading message carries the whole grading: replace what you had for that game and product.
  • REST: GET /v1/{product}/grading/{eventId} for one game, and GET /v1/{product}/grading?updatedSince=… for every grading revised since then, where {product} is live, pregame or props.
  • GET /v1/events/{eventId} lists, under grading, 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); otherwise void, 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.