Sportsbook API Integration: Odds, Bets and Settlement
A sportsbook storefront can display a market within milliseconds, yet a displayed price is not a promise that a bet will be accepted. Odds data, the operator's risk and ticket service, the wallet ledger and settlement feeds are different systems with different authority. A reliable sportsbook API integration connects them through documented identities, state transitions, retry rules and reconciliation. This guide follows a ticket from a live market through price validation and acceptance to a final or corrected settlement. Feed examples are illustrative: receiving odds from a supplier does not establish that the supplier accepts bets, holds the wallet or grants operating rights.
Published
A sportsbook integration keeps market data, ticket acceptance and financial settlement as separate controlled decisions.
On this page
What does a sportsbook API integration actually include?
An integration usually joins at least three concerns: a catalog of fixtures, markets and changing odds; a bet-placement or trading service with its own acceptance rules; and a settlement process that produces the financial result. These concerns might come from one commercial supplier or several separate services. Document the owner of each operation before building an adapter. [1]
A feed event can be authoritative for its own market state without being authorized to move money. Likewise, a successful ticket API response is the source of truth for the accepted stake and price only if the contracted integration defines it that way. Never infer acceptance from a user's click or an odds-update acknowledgement.
How are fixture, market and selection IDs mapped?
Use stable internal references for event, market, outcome and ticket, but retain the full supplier namespace and raw identifiers. An event can have multiple markets, and one market can have several selections and lines. A display label such as 'Over 2.5' is not a unique API key; it needs its market, specifier and event context.
Identifier
What it identifies
Safety rule
Source event ID
Fixture in a supplier feed
Keep provider namespace
Market ID
Type of wager for an event
Include market specifiers
Selection ID
Specific possible outcome
Do not key on label
Price version
Observed quote revision
Reject stale assumptions
Ticket ID
Accepted customer bet
Never reuse on retry
Settlement reference
Source result event
Link to original ticket
Store the mapping version and the original feed payload so that a renamed fixture, rescheduled match or changed market line does not silently attach an existing ticket to a different event. The feed's message types distinguish fixture, odds and settlement information. [1]
How do odds updates and market suspension affect a bet?
Odds can change or a market can stop accepting wagers between page display and server-side submission. The consumer must apply the supplier's market status semantics, freshness policy and version ordering. A paused market should not be made bettable merely because the last visible numeric price still looks valid. Sportradar's odds_change and market status examples illustrate this separation. [2]
Preserve feed timestamp, source ID and last applied update per event and market.
Distinguish active, suspended, closed and unknown states according to the actual contract.
Define a maximum age for displayed prices and server-side confirmation of the quoted version.
Never turn a stale feed into an implicit guarantee that a ticket can be accepted.
A cache can serve market discovery quickly, but the acceptance endpoint must re-evaluate the current authoritative price, risk limits and eligibility. If the quotation changed, return an explicit price-change or rejection outcome rather than silently charging the older request.
What happens between clicking Bet and an accepted ticket?
A bet request should identify customer, brand, market, outcome, proposed stake, quoted price and a unique client request key. The ticket engine checks market state, account eligibility, stake and exposure limits, funding and any supplier-specific acceptance condition. Do not assume an odds feed is also the bet-acceptance endpoint.
Receive the customer's intended stake, selection and quoted odds with a unique request ID.
Ask the contracted ticket or trading service for a definitive accepted, rejected or pending outcome.
Commit one ticket and one wallet reservation or debit, then return the stored result on safe retries.
⊕View largerThe live odds stream informs the ticket engine, but only the confirmed acceptance state creates a financial obligation.
A timeout after submission is an ambiguous outcome: the partner might have accepted the ticket even if the operator received no response. Query by the request key or ticket reference before retrying. HTTP semantics do not make repeated non-idempotent POST requests safe by default. [6]
How should feed messages be ordered, replayed and recovered?
Live feeds can disconnect, deliver delayed updates or require a snapshot after a gap. Keep producer/session identity, ordering metadata, a recovery cursor and an audited checkpoint. A message acknowledgement should occur only after the consumer has durably recorded the required state. Sportradar documents recovery workflows and the need to process stateful settlement and cancel messages. [5]
Scenario
Required action
Check before resume
Duplicate update
Ignore repeat via source key
No duplicate market change
Sequence gap
Suspend unsafe market use
Replay or fetch snapshot
Feed outage
Apply staleness safeguards
Confirm producer health
Late settlement
Process as distinct event
Ticket and ledger linkage
Replay after restart
Resume durable cursor
No repeated payout
A recovered odds snapshot does not automatically prove that every settlement message has been applied. Check the provider's actual recovery contract, partitioning and retention limits; reconcile outstanding tickets separately before declaring the system current.
How are results, void bets and rollbacks handled?
Settlement uses result information to close an accepted ticket under its agreed betting rules. Outcomes may be win, loss, void, partial settlement or another provider-defined status; the integration must map them explicitly, including combinations and multi-leg tickets where supported. Sportradar documents both bet_settlement and a separate rollback_bet_settlement event. [3] [4]
Store the original accepted stake, price, market and rule version with the ticket.
Accept settlement messages only for known tickets and valid provider event identities.
Post a documented payout, void or liability adjustment once using a unique settlement key.
When a correction arrives, record a new reversing entry and the reason instead of deleting history.
A rollback is not a new winning outcome, and a cancellation is not always the same as a voided settlement. Preserve the source message type and audit trail. Where Great Britain's rules apply, the UK Gambling Commission expects result handling to follow the operator's published rules and affected customers to be informed of relevant errors. [7]
How does the sportsbook wallet reconcile stakes and payouts?
The wallet and bet ledger need separate immutable references for stake reservation, accepted ticket, settlement and later correction. A ticket should never be considered paid just because a callback was received. Apply each financial event under a unique posting key and compare wallet movement with accepted ticket state and external settlement evidence.
Ticket state
Wallet treatment
Audit evidence
Quoted only
No stake debit
Quote request and expiry
Accepted
Reserve or debit stake once
Accepted ticket reference
Rejected
No committed stake charge
Rejection or release record
Settled
Pay win or close loss
Outcome and posting ID
Corrected / void
Reversal or refund entry
Prior entry plus reason
Reconciliation needs exact balance deltas by ticket, currency and ledger entry, including pending reservations and reversals. Investigate mismatches instead of creating compensating credits from raw callbacks; account for time zones and numeric precision according to the payment and wallet contract.
Which latency and risk controls matter for in-play betting?
In-play markets are time-sensitive. A low-latency odds stream improves display freshness but does not replace suspension signals, a controlled quote-to-acceptance window, exposure limits or market-specific bet delays. Define failure behavior when timeouts, event suspensions or risk service outages occur rather than accepting the last displayed odds.
Measure source-to-consumer lag, customer quote age and acceptance response time separately.
Treat market suspension, stale data or risk-service uncertainty as a controlled hold or rejection.
Record the actual accepted price independently of what the customer viewed seconds earlier.
Test rapid odds changes, event corrections and consecutive submissions under load.
Operators should make acceptance and rejection clear to the customer. Different markets and jurisdictions have different conditions; never promise a universal settlement time, acceptance rate or guaranteed odds from a generic API architecture. [2] [7]
What security, compliance and monitoring must be tested?
Protect sportsbook commands with authenticated service identities, authorization scoped to customer and brand, secret rotation, encrypted transport, rate limits and a tamper-evident audit trail. Separate read-only feed consumers from systems allowed to accept tickets or post wallet entries; enforce object-level access for every bet reference.
Alert on stale prices, feed gaps, suspended-market acceptance attempts and unknown event IDs.
Reconcile accepted, pending and settled tickets against the supplier's permitted reports.
Test duplicate POSTs, retries after timeout, rollback order and tampered settlement callbacks.
Document local licensing, consumer rules, data retention and dispute workflows for each target market.
Monitor technical feed health and financial correctness with separate dashboards. An 'all messages processed' count is not enough if wallet reconciliation still shows open liabilities, duplicate payouts or unmatched customer tickets.
What is the launch checklist for a sportsbook API?
Test the entire ticket life cycle with recorded fixtures and expected outcomes: live and prematch price changes, suspended markets, bet rejection, successful acceptance, late results, voids, rollbacks, feed recovery and disputed wallet balances. Keep each case traceable from source message to final ledger entry.
Verify market and selection IDs, contract scopes, odds precision and quote expiration.
Prove settlement, cancellation, rollback and financial reconciliation on a test ledger.
Obtain the required operational, security, market and legal sign-offs before live enablement.
A production-ready sportsbook integration does more than display odds and return a bet ID. It proves that every customer ticket has one explainable acceptance decision, each result is interpreted under the proper rules, and every financial correction remains auditable.