The Bet Settlement API That Returns the Verdict
You hold a list of bets. You want to know which ones won. Send the event, market, line and side, and get back won, lost, void, half won or half lost, graded from final scores for 64 markets in 20 sports.
Included on every paid plan. Each call counts as one request.
Grade Three Bets in One Request
This match finished 3-2 after 90 minutes and 3-3 after extra time. Football settles on 90 minutes, so the home moneyline won, and basis shows the score that was used.
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" }
]
}'{
"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 } }
]
}How Bet Settlement Works
Two endpoints. GET /v3/settlements tells you what happened in up to 50 events. POST /v3/settlements/grade tells you whether your bets won.
- 1
Store the bet
When a bet is placed, keep the event id, market, line and side. They are the same four fields you already get from /v3/odds, so there is nothing to map.
- 2
Send it for grading
After the match, POST up to 50 selections to /v3/settlements/grade. Each one comes back as won, lost, void, half_won or half_lost. Most score markets also return the score the grade was based on.
- 3
Settle when the result is final
Every answer carries a final flag. Keep the selections where final is false and send them again later. Once a minute is the most often you need to.
Seven Possible Answers
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.
- won
- The bet won
- lost
- The bet lost
- half_won
- Quarter line: half the stake won, half is returned
- half_lost
- Quarter line: half the stake lost, half is returned
- void
- Stake returned. The reason is push or event_cancelled
- pending
- Not decided yet. The reason says what we are waiting for
- ungradeable
- We cannot prove the answer. The reason says why
Settlement Rules You Can Read
The rules follow common bookmaker practice. Books differ on details, so check them against your own terms.
Football settles on 90 minutes
Football, futsal, handball and rugby markets settle on regulation time. Extra time and penalty shootouts never count, even when the match score includes them.
Overtime where books count it
In basketball, American football, baseball and ice hockey, the moneyline, spread and totals include overtime and extra innings. 3-Way Result, Double Chance and Draw No Bet settle on regulation time.
Quarter lines split the stake
An Asian handicap of -0.75 is half on -0.5 and half on -1. When the home team wins by one, the answer is half_won. A whole line that lands exactly is void with reason push.
Cancelled matches are void
Every bet on a cancelled event comes back void with reason event_cancelled. If the match is rescheduled later, the event goes back to pending under the same id.
Corners and bookings from match statistics
Football corners, bookings and first team to score are graded from post-match statistics, about 30 minutes after full time. Until then the answer is pending with reason awaiting_stats.
Player props from the box score
Props are graded for basketball, baseball, ice hockey and American football. We match the player by name and refuse when the name could be two people.
64 Markets in 20 Sports
Market names are the ones /v3/odds serves. The settlement guide lists every market by sport.
Main lines
ML, 3-Way Result, Spread and Asian handicaps, Totals, Team Totals, European Handicap, Double Chance, Draw No Bet, Both Teams To Score, Odd/Even
Halves, quarters and innings
Half-time and second-half versions of the main lines, Half Time / Full Time, first quarter spread and totals, First 5 Innings and 1st Inning markets in baseball
Tennis and esports
Games handicap and total games, set winners and set totals in tennis. Map Handicap, Total Maps and 1st Map ML in esports
Football statistics
Corners totals and spreads, bookings totals and spreads, team and half-time versions of both, First Team To Score
Player props
Over and under lines from the official box score in basketball, baseball, ice hockey and American football
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
How Often a Bet Is Graded
We ran 22,903 bets that our own bet tracker settled in the 30 days to 12 October 2026 through this API. This is the share that came back with a verdict.
- Baseball, score markets
- 99.6%
- Ice hockey, score markets
- 99.2%
- Basketball, score markets
- 99.1%
- American football, score markets
- 98.5%
- Football, score markets
- 98.0%
- Football bookings
- 88.3%
- Football corners
- 82.4%
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. The rest came back ungradeable with a reason.
Bet Settlement API FAQ
How do I settle bets automatically 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 on the Odds-API.io v3 API. The response says won, lost, void, half_won or half_lost for each bet, and the final flag tells you when the result is confirmed.
What is a bet settlement API?
A bet settlement API takes a bet you hold and tells you how it ended. You send the event, market, line and side, and it returns the result from the final score. Bet trackers, tipster platforms, prediction games and sportsbook back offices use one so they do not have to write grading rules for every market and sport.
Which markets and sports can the API grade?
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.
Can it settle Asian handicap bets with quarter lines?
Yes. Send them as Spread with the line in hdp. The handicap is always stated for the home team. Quarter lines such as -0.75 return half_won or half_lost when half the stake is returned, and a whole line that lands exactly returns void with reason push.
Does a football bet settle on 90 minutes or after extra time?
On 90 minutes plus stoppage time. Football, futsal, handball and rugby bets settle on regulation time, even when the match went to extra time or penalties. Grades on most score markets include the score they were based on, so you can show it to your users. Half Time / Full Time, corners, bookings and player props return the verdict only.
What happens when a match is postponed or cancelled?
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. A match that never gets a result turns ungradeable with reason result_unavailable 72 hours after kickoff.
How soon after a match can I settle a bet?
Score markets are usually ready a few minutes after the final whistle. Corners, bookings and player props take about 30 minutes. Until then the answer is pending. The final flag turns true once the result has been checked against the official one, or 48 hours after the match ended.
Which plans include the settlement API?
Both settlement endpoints are on every paid plan and each call counts as one request. GET /v3/settlements takes up to 50 event ids and POST /v3/settlements/grade takes up to 50 selections.
Explore More
Stop Writing Grading Rules
Settlement comes with the same key as odds from 365+ bookmakers. Pick a paid plan and send your first selections today.