Bet Settlement API

What the settlement API does

You hold a list of bets. You want to know which ones won. The settlement API answers that in two calls:

Endpoint	Question it answers	Plans
`GET /v3/settlements`	What happened in these events? Is the result final?	Paid
`POST /v3/settlements/grade`	Did these bets win?	Paid

You send the event, the market, the side and the line, the same four things you already get from /v3/odds. We send back won, lost, void, half_won or half_lost. It covers 64 markets in 20 sports: moneyline, spreads and Asian handicaps, totals, both teams to score, double chance, draw no bet, half-time markets, tennis games and sets, esports maps, football corners and bookings, and player props in basketball, baseball, ice hockey and American football. One rule runs through all of it. We only grade a bet when the stored result proves the answer. If something is missing or does not add up, you get ungradeable with a reason, never a guess.

Quick start

1. Check what happened

curl "https://api.odds-api.io/v3/settlements?apiKey=YOUR_API_KEY&eventIds=74919888,73101436"

const apiKey = process.env.ODDS_API_KEY;
const ids = [74919888, 73101436].join(',');

const res = await fetch(
  `https://api.odds-api.io/v3/settlements?apiKey=${apiKey}&eventIds=${ids}`
);
const { settlements, notFound } = await res.json();

import os
import requests

res = requests.get(
    "https://api.odds-api.io/v3/settlements",
    params={"apiKey": os.environ["ODDS_API_KEY"], "eventIds": "74919888,73101436"},
)
data = res.json()

{
  "settlements": [
    {
      "eventId": 74919888,
      "sport": "Football",
      "status": "settled",
      "final": true,
      "settledAt": "2026-10-11T15:39:12Z",
      "scores": {
        "home": 3,
        "away": 3,
        "periods": {
          "p1": { "home": 1, "away": 2 },
          "p2": { "home": 2, "away": 0 },
          "ft": { "home": 3, "away": 2 },
          "ot": { "home": 3, "away": 3 }
        }
      }
    }
  ],
  "notFound": []
}

Every id you send gets an answer. A cancelled match comes back with "status": "cancelled". An id we have never seen is listed in notFound.

2. Grade your bets

curl -X POST "https://api.odds-api.io/v3/settlements/grade?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selections": [
      { "ref": "bet-1", "eventId": 74919888, "market": "ML", "side": "home" },
      { "ref": "bet-2", "eventId": 74919888, "market": "Spread", "hdp": -0.75, "side": "home" },
      { "ref": "bet-3", "eventId": 74919888, "market": "Totals", "hdp": 5.5, "side": "over" }
    ]
  }'

const res = await fetch(
  `https://api.odds-api.io/v3/settlements/grade?apiKey=${apiKey}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      selections: [
        { ref: 'bet-1', eventId: 74919888, market: 'ML', side: 'home' },
        { ref: 'bet-2', eventId: 74919888, market: 'Spread', hdp: -0.75, side: 'home' },
        { ref: 'bet-3', eventId: 74919888, market: 'Totals', hdp: 5.5, side: 'over' },
      ],
    }),
  }
);
const { grades } = await res.json();

res = requests.post(
    "https://api.odds-api.io/v3/settlements/grade",
    params={"apiKey": os.environ["ODDS_API_KEY"]},
    json={
        "selections": [
            {"ref": "bet-1", "eventId": 74919888, "market": "ML", "side": "home"},
            {"ref": "bet-2", "eventId": 74919888, "market": "Spread", "hdp": -0.75, "side": "home"},
            {"ref": "bet-3", "eventId": 74919888, "market": "Totals", "hdp": 5.5, "side": "over"},
        ]
    },
)
grades = res.json()["grades"]

{
  "grades": [
    { "ref": "bet-1", "eventId": 74919888, "result": "won", "reason": null, "final": true,
      "basis": { "scope": "regulation", "home": 3, "away": 2 } },
    { "ref": "bet-2", "eventId": 74919888, "result": "half_won", "reason": null, "final": true,
      "basis": { "scope": "regulation", "home": 3, "away": 2 } },
    { "ref": "bet-3", "eventId": 74919888, "result": "lost", "reason": null, "final": true,
      "basis": { "scope": "regulation", "home": 3, "away": 2 } }
  ]
}

This match finished 3-2 after 90 minutes and 3-3 after extra time. Football bets settle on 90 minutes, so the home moneyline won. basis shows you the score we used. Grades come back in the order you sent the selections, and ref is echoed so you can match them to your own records. You can send up to 50 selections in one request, on as many events as you like.

How to describe a bet

A selection uses the same fields as an odds row from /v3/odds. If you stored the market, line, label and side when the bet was placed, send them back unchanged.

Field	Required	What to send
`eventId`	Yes	The event id, as a number or a string
`market`	Yes	The market name as we serve it: `ML`, `Spread`, `Totals HT`, `Corners Totals`, `Player Props`
`side`	Yes	`home`, `away`, `draw`, `over`, `under`, `yes`, `no`, `odd`, `even`, `1x`, `12`, `x2`, `none`, or a pair such as `draw/home` for half time / full time
`hdp`	For markets with a line	The line as served. Handicaps are stated for the home side. For totals it is the total
`label`	For player props	The row label as served, for example `Arike Ogunbowale (Assists)`
`tieRule`	No	`lose` or `void`. See ties on the moneyline
`ref`	No	Your own id for the bet. We send it back

Market names are matched exactly, apart from upper and lower case. Corners Totals is not Totals, and Spread HT is never graded on the full-time score. A name we do not recognise comes back as unsupported_market. We never pick the closest match.

The handicap is always the home team’s. If the row says Spread with hdp: -1.5 and you backed the away team, send "side": "away" with "hdp": -1.5. We work out that your side is +1.5.

Reading the answer

`result`	Meaning
`won`	The bet won
`lost`	The bet lost
`half_won`	Quarter-line bet: half the stake won, half is returned
`half_lost`	Quarter-line bet: half the stake lost, half is returned
`void`	Stake returned. `reason` says why: `push` or `event_cancelled`
`pending`	Not decided yet. `reason` says what we are waiting for
`ungradeable`	We cannot settle this bet for you. `reason` says why

reason is null for won, lost, half_won and half_lost. It is always filled in for void, pending and ungradeable.

`reason`	Goes with	What it means
`push`	`void`	Landed exactly on the line, or a tie where the stake is returned
`event_cancelled`	`void`	The match was cancelled or postponed
`event_not_started`	`pending`	The match has not kicked off
`event_live`	`pending`	The match is being played
`awaiting_result`	`pending`	The match is over and we are confirming the result
`awaiting_stats`	`pending`	We are waiting for final corners, cards or box scores
`event_not_found`	`ungradeable`	We do not know this event id
`unsupported_market`	`ungradeable`	We do not grade this market, or not for this sport
`invalid_side`	`ungradeable`	This side does not exist on this market
`invalid_line`	`ungradeable`	The line is missing, or the market has no line
`invalid_label`	`ungradeable`	The label is missing or does not belong on this market
`incomplete_score`	`ungradeable`	The score this market needs is missing or does not add up
`ambiguous_tie`	`ungradeable`	A level score on a moneyline where we need your tie rule
`player_not_matched`	`ungradeable`	We could not identify the player with certainty
`stats_unavailable`	`ungradeable`	The statistic this market needs was not recorded
`result_unavailable`	`ungradeable`	More than 72 hours after kickoff and no result exists

When is a result final?

Every answer carries final. Read it as “you can stop checking”. Scores are sometimes corrected in the first hours after a match. We check each result against the official one, and final turns true once that check is done, or 48 hours after the match ended. A simple loop that works:

Grade your open bets.
Pay out or settle on any answer you are comfortable with. Most products wait for final: true.
Keep the selections where final was false, and send them again later. Once a minute is the most often you need to.

Check final on each grade, not on the event. An event can be final while a player prop on it is still awaiting_stats.

A cancelled event becomes final 48 hours after its scheduled kickoff. If the match is rescheduled later, the event goes back to pending under the same event id. Whether a bet you already voided stays void is your rule to set; many bookmakers void a match that is not played within 48 hours.

How bets are settled

These are the rules this API applies. They follow common bookmaker practice, but books differ on details, so check them against your own terms.

Which score counts

Football, futsal, handball, rugby. Every market settles on regulation time. In football that is 90 minutes plus stoppage time. Extra time and penalty shootouts never count.
Basketball, American football, baseball, ice hockey. ML, Spread, Totals, team totals, Odd/Even and Both Teams To Score include overtime and extra innings. 3-Way Result, Double Chance, European Handicap and Draw No Bet settle on regulation time.
Ice hockey shootouts. The shootout winner gets one goal added. A game that is 2-2 after overtime and won in a shootout is a 3-2 win for totals and handicaps too.
Tennis, volleyball, table tennis, badminton, padel. The match score is sets. Esports is maps. Darts and snooker use the match score. MMA and boxing use the winner.

Half lines and quarter lines

A whole-number line can land exactly, and then the bet is void with reason push. A quarter line (-0.25, 2.75) is two bets at the lines either side. Home -0.75 when the home team wins by one is half on -0.5 (won) and half on -1 (pushed), so the answer is half_won.

Ties on the moneyline

3-Way Result always has a draw, so a level score means draw wins and both teams lose. MMA and boxing are the exception to both rules. We store the winner of a fight, and a result with no winner could be a draw or a no contest. Those bets come back incomplete_score, whatever tieRule says. ML depends on the sport:

Sport	Level score on `ML`
Football, futsal, handball	The draw is its own outcome. `home` and `away` lose, `draw` wins
American football, baseball	`void` with reason `push`
Everything else	Depends on the bookmaker. Send `tieRule`

In sports such as rugby and Aussie rules, some bookmakers offer the moneyline with a draw price and some without. We cannot know which kind your bet was. Send "tieRule": "lose" if the draw was a separate outcome at your book, or "tieRule": "void" if stakes are returned. Without it you get ambiguous_tie, and only when the score really was level.

Cancelled and postponed matches

Every bet on a cancelled event comes back void with reason event_cancelled. Postponed and abandoned matches are usually reported as cancelled too. A match that never gets a result and is never marked cancelled stays pending with reason awaiting_result, and turns ungradeable with reason result_unavailable 72 hours after kickoff. That includes a market that was already decided when a match was abandoned, such as over 0.5 goals after a goal had been scored.

Tennis

We grade a tennis match when the stored set scores show that it was played to the end: the winner has the sets needed, and every set is a finished set. If a player retires or gives a walkover, the bet comes back incomplete_score and you apply your own retirement rule. Some tennis results arrive without game scores for each set. Those also come back incomplete_score. Spread (Games) and Totals (Games) add up the games in every set. A match decided by a match tie-break is not graded on games markets.

Corners, bookings and first team to score

These are football only and are graded from post-match statistics. They are ready about 30 minutes after full time. Until then the answer is pending with reason awaiting_stats.

Corners count each team’s corners.
Bookings use booking points: a yellow card is 1, a red card is 2, and a second yellow that becomes a red adds 2 more.
First Team To Score follows the scoreboard, so an own goal counts for the team whose score went up. A match that is 0-0 after 90 minutes settles as none.

Full-match corners and bookings are only graded for matches with no extra time, because the stored totals cover the whole match. For these markets you get the verdict without the underlying count.

Player props

Send "market": "Player Props" with the label as served, such as LeBron James (Points), the line in hdp, and over or under. Props are graded for basketball, baseball, ice hockey and American football, from the official box score. We match the player by name and refuse when the name could be two people. A player who does not appear in the box score comes back player_not_matched. We do not assume the player sat out.

Supported markets

Market	Sports
`ML`, `Moneyline`	All 20 sports
`3-Way Result`	Football, futsal, handball, rugby, Aussie rules, basketball, American football, baseball, ice hockey, MMA, boxing
`Spread`, `Totals`	Football, futsal, handball, rugby, Aussie rules, basketball, American football, baseball, ice hockey, tennis, table tennis, volleyball, beach volleyball, badminton, padel, esports
`Goals Over/Under`	Football
`Team Total Home`, `Team Total Away`	Football, futsal, handball, rugby, Aussie rules, basketball, American football, baseball, ice hockey
`European Handicap`, `Double Chance`, `Draw No Bet`, `Both Teams To Score`, `Odd/Even`	The same team sports
`Half Time / Full Time`	Football, futsal, handball, rugby, basketball, American football
`ML HT`, `Spread HT`, `Totals HT`, `Team Total Home HT`, `Team Total Away HT`, `European Handicap HT`, `Double Chance HT`, `Draw No Bet HT`, `Both Teams To Score HT`	Football, futsal, handball, rugby, Aussie rules, basketball, American football
`ML 2H`, `Spread 2H`, `Totals 2H`, `European Handicap 2H`, `Both Teams To Score 2H`	Football, futsal, handball, rugby, basketball, American football
`Spread 1Q`, `Totals 1Q`	Basketball, American football, Aussie rules, ice hockey (first period)
`First 5 Innings ML`, `First 5 Innings Spread`, `First 5 Innings Totals`, `1st Inning ML`, `1st Inning Totals`	Baseball
`Spread (Games)`, `Totals (Games)`, `ML 2nd Set`, `Totals 2nd Set`, `ML 3rd Set`	Tennis
`ML 1st Set`, `Totals 1st Set`	Tennis, volleyball
`Map Handicap`, `Total Maps`, `1st Map ML`	Esports
`Corners Totals`, `Corners Spread`, `Corners Totals Home`, `Corners Totals Away`, `Alternative Corners`	Football
`Corners Totals HT`, `Corners Spread HT`, `Corners Totals Home HT`, `Corners Totals Away HT`	Football
`Bookings Totals`, `Bookings Spread`, `Bookings Totals Home`, `Bookings Totals Away`	Football
`Bookings Totals HT`, `Bookings Spread HT`, `Bookings Totals Home HT`, `Bookings Totals Away HT`	Football
`First Team To Score`	Football
`Player Props`	Basketball, baseball, ice hockey, American football

In basketball and American football the second half includes overtime. Not graded yet: correct score, goalscorer markets, winning margin, football player props, American football anytime touchdown props, cricket, and outrights. They come back unsupported_market.

Why some bets come back ungradeable

A wrong grade costs you money and a customer’s trust. An ungradeable one costs a manual check. So we refuse whenever the stored data cannot prove the answer. For example:

A football result with no 90-minute score recorded, where we cannot rule out extra time.
A basketball score that is lower than the sum of its quarters.
A tennis match that stopped before the last set was finished.
A player prop where two players in the game share the name on the bet.

To give you a feel for how often that happens, we ran 22,677 bets that our own bet tracker settled in the 30 days to 11 October 2026 through this API.

Bets	Settled automatically
Football, score markets	98.0%
Basketball, score markets	99.1%
Ice hockey, score markets	99.2%
American football, score markets	99.8%
Baseball, score markets	99.6%
Handball, score markets	97.3%
Esports	100%
Tennis	65.8%
Football corners	82.2%
Football bookings	89.7%
Player props, basketball, baseball and ice hockey	99%

Tennis is lower because many tennis results arrive without game scores, and we do not grade those. Treat these numbers as a guide. They come from one month of one product’s bets, mostly football main markets, on events that had already been settled once.

Limits and plans

Both endpoints are on every paid plan and each call counts as one request.
GET /v3/settlements takes up to 50 event ids.
POST /v3/settlements/grade takes up to 50 selections and a request body of up to 64 KB.
Free plans get a 403. You can still read final scores from /v3/historical/events.

Frequently asked questions

How do I settle a bet with an API?

Store the event id, market, line and side when the bet is placed. After the match, send them to POST /v3/settlements/grade. The response says won, lost, void, half_won or half_lost for each bet, and final tells you when the result is confirmed.

Does the score include extra time?

Not for football. Football, futsal, handball and rugby bets settle on regulation time, and we grade them on the 90-minute score even when the match went to extra time or penalties. In basketball, American football, baseball and ice hockey, the moneyline, spread and totals include overtime.

What happens when a match is postponed or abandoned?

In most cases the event status becomes cancelled, and every bet on it grades as void with reason event_cancelled. If the match is rescheduled later, the event goes back to pending under the same id. If a match is never marked cancelled and never gets a result, its bets stay pending with reason awaiting_result, then turn ungradeable with reason result_unavailable 72 hours after kickoff.

Can I settle Asian handicap bets, including quarter lines?

Yes. Send them as Spread with the line in hdp. Quarter lines return half_won or half_lost when half the stake is returned.

Can I settle player props?

Yes, for basketball, baseball, ice hockey and American football. Send Player Props with the label, such as Nikola Jokic (Rebounds), and the line.

Can I settle corners and cards?

Yes, for football. Use Corners Totals, Corners Spread, Bookings Totals, Bookings Spread and their team and half-time versions. They are graded about 30 minutes after full time.

How soon after a match can I settle?

Score markets are usually ready a few minutes after the final whistle. Statistics markets take about 30 minutes. Until then the answer is pending.

What does `final: false` mean?

The answer is our current result, but the score has not been confirmed against the official one yet. Corrections are rare. If you pay out on results that are not final, check them again later.

Why did my bet come back `ungradeable`?

Read reason. It is either something in the request, such as a market name we do not grade or a missing line, or it is the data: the score or statistic the market needs was not recorded in a way we can trust.

Do I need to tell you which bookmaker the bet was placed with?

No. Settlement uses the result of the event, not a bookmaker’s own grading. The one place bookmakers differ is a tie on the moneyline in a few sports, which is what tieRule is for.

Fetching odds: where the market, line and side for each selection come from.
Historical odds: closing lines and results for past events.
API reference: full request and response schemas.

Getting Started

Guides

Examples

What the settlement API does

Quick start

1. Check what happened

2. Grade your bets

How to describe a bet

Reading the answer

When is a result final?

How bets are settled

Which score counts

Half lines and quarter lines

Ties on the moneyline

Cancelled and postponed matches

Tennis

Corners, bookings and first team to score

Player props

Supported markets

Why some bets come back ungradeable

Limits and plans

Frequently asked questions

How do I settle a bet with an API?

Does the score include extra time?

What happens when a match is postponed or abandoned?

Can I settle Asian handicap bets, including quarter lines?

Can I settle player props?

Can I settle corners and cards?

How soon after a match can I settle?

What does `final: false` mean?

Why did my bet come back `ungradeable`?

Do I need to tell you which bookmaker the bet was placed with?

​What the settlement API does

​Quick start

​1. Check what happened

​2. Grade your bets

​How to describe a bet

​Reading the answer

​When is a result final?

​How bets are settled

​Which score counts

​Half lines and quarter lines

​Ties on the moneyline

​Cancelled and postponed matches

​Tennis

​Corners, bookings and first team to score

​Player props

​Supported markets

​Why some bets come back ungradeable

​Limits and plans

​Frequently asked questions

​How do I settle a bet with an API?

​Does the score include extra time?

​What happens when a match is postponed or abandoned?

​Can I settle Asian handicap bets, including quarter lines?

​Can I settle player props?

​Can I settle corners and cards?

​How soon after a match can I settle?

​What does final: false mean?

​Why did my bet come back ungradeable?

​Do I need to tell you which bookmaker the bet was placed with?

​Related

What the settlement API does

Quick start

1. Check what happened

2. Grade your bets

How to describe a bet

Reading the answer

When is a result final?

How bets are settled

Which score counts

Half lines and quarter lines

Ties on the moneyline

Cancelled and postponed matches

Tennis

Corners, bookings and first team to score

Player props

Supported markets

Why some bets come back ungradeable

Limits and plans

Frequently asked questions

How do I settle a bet with an API?

Does the score include extra time?

What happens when a match is postponed or abandoned?

Can I settle Asian handicap bets, including quarter lines?

Can I settle player props?

Can I settle corners and cards?

How soon after a match can I settle?

What does `final: false` mean?

Why did my bet come back `ungradeable`?

Do I need to tell you which bookmaker the bet was placed with?

Related