Cash-out Description and Flow
The Cashout feature allows bettors to settle a bet before its conclusion — locking in profit or limiting loss. Cashout values may vary from the original ticket payout based on how the event is evolving (market odds, selections settled/lost, etc.).
With the updated Cashout Engine, clients may use one or more of the following operations:
cashout-inform
Inform MTS that the client has already executed a full or partial cash-out
The client executes the cash-out; MTS performs basic validation and records the result
When the operator wants to retain control over cash-out calculation and execution
cashout-placement
Submit a cash-out for real-time validation and finalisation
MTS performs the final validation and, if accepted, finalises the cash-out
When cash-out risk management and final validation should be handled by MTS
cashout-build
Request the current cash-out values and supporting information once or repeatedly
MTS calculates and returns current values; the client decides when to display or use them
When the client needs point-in-time cash-out information
cashout-build-subscription
Request ongoing cash-out build updates for a ticket or bet
MTS monitors the subscribed target and sends updated cashout-build-reply messages after recalculation
When the client wants push-based updates instead of repeatedly polling with cashout-build
auto-cashout
Register a threshold-based cash-out instruction
MTS monitors the configured threshold and notifies the client when it is fulfilled
When the bettor or client wants MTS to monitor a take-win or other supported threshold
When MTS processes and accepts the cashout request, the liabilities will be recalculated accordingly. The receipt of cash-out information does not immediately affect invoicing for the MTS services between Sportradar and the client.
Cashout reason codes
End customer triggered bet cashout
It should be used to request a cashout when a bettor has opted to do so.
Cashout flow examples
The following examples illustrate how the three cashout operations work in real-world scenarios. They show the interaction between the bettor, the operator, and Sportradar’s Cashout Engine, and how different levels of control and validation come into play.
Cashout Build & Placement (Full Risk Delegation)
A bettor opens the operator’s app during a live football match and goes to the My Bets or Cashout section.
The operator immediately starts calling the
cashout-buildoperation in regular intervals.Sportradar responds with all relevant insights: bettor profile (confidence value, late bet score, marker score, bot score), event profile (event ratings, recommended live time delay), market profile (market rating, probabilities), and calculated values (fair and margin-adjusted cashout offers, plus the max potential win).
The operator’s app displays the margin-adjusted cashout value to the bettor. Because the bettor has a high confidence value and the event is volatile, the value is already adjusted to reflect those factors.
The bettor accepts the displayed offer and presses the "Cash Out" button, sending full or partial cashout request. The operator now sends a
cashout-placementrequest to MTS that reflects bettor's selection.Sportradar validates the request against fair or margin-adjusted values (depending on the operator's preferences), market conditions (betting and cashout statuses), and live time delay rules.
If accepted, the cashout is finalised and liabilities are recalculated automatically. The bettor sees a confirmation in the app and the balance is updated instantly.
This flow combines the transparency of cashout-build with the risk management of cashout-placement, giving operators strong guarantees without losing frontend flexibility.
Cashout Build Subscription
cashout-build-subscription provides asynchronous cash-out build updates for a ticket or bet.
Unlike cashout-build, which is requested whenever the client needs a current value, the subscription keeps the target active for a limited period. MTS recalculates the cash-out value when relevant event, market, settlement, or other cash-out state changes are received and sends an updated cashout-build-reply to the client.
The subscription does not reserve a cash-out value and does not execute a payout.
The typical sequence is:
The client sends a
cashout-build-subscriptionrequest for an eligible ticket or bet.MTS validates and registers the subscription.
MTS monitors the subscribed target and processes relevant updates.
MTS sends a
cashout-build-replyafter each applicable recalculation.The client displays or uses the latest returned value.
The client finalises the cash-out using either:
cashout-placement, if MTS should perform the final validation and execution; orcashout-inform, if the client performs the cash-out locally.
The subscription remains active for five minutes from creation unless it is terminated earlier by a terminal ticket or bet event or by an explicitly supported termination mechanism.
The latest build reply is point-in-time information. It must not be treated as a guaranteed quote or as confirmation that a cash-out has been executed. The client must use the current value and handle the possibility that a later placement request is rejected or accepted with a changed value.
cashout-build vs. cashout-build-subscription
Use cashout-build when the client controls when a calculation is requested. This is suitable for demand-driven polling while a bettor is viewing a ticket.
Use cashout-build-subscription when the client wants MTS to continue monitoring a ticket or bet and send updated build results asynchronously.
Behaviour
cashout-build
cashout-build-subscription
Request model
Client requests a calculation
Client creates a temporary subscription
Result delivery
One reply for each request
Multiple replies may be sent for one subscription
Client polling
Recommended at the applicable client-side interval
Not required for subscribed updates
Monitoring period
Ends with the request/response cycle
Active for up to five minutes
Payout execution
Does not execute a payout
Does not execute a payout
Finalisation
Follow with placement or inform
Follow with placement or inform
Stale-value handling
A later request can obtain a new value
Use the latest received reply and validate again through placement
Cashout Inform Only (Operator Controlled, MTS Aware)
cashout-inform is used when the client calculates, accepts, and executes the cash-out locally.
The sequence is:
The client calculates and displays a cash-out offer.
The bettor accepts the offer.
The client executes the payout locally.
The client sends
cashout-informto MTS.
MTS performs basic validation and records the cash-out for reporting and liability purposes. The inform operation does not delegate the full cash-out risk decision to MTS.
cashout-inform is not required after an accepted cashout-placement.
For unsupported or mixed-provider tickets, cashout-inform may remain available when managed cash-out through cashout-build and cashout-placement is not available. In that case, the cash-out is not risk-managed by MTS.
Cashout Build & Inform (Data-Enriched Operator Logic)
Some operators might prefer a hybrid model, where they keep execution control but enrich their logic with Sportradar’s data.
A bettor taps “Cash Out.” The operator calls
cashout-build.Sportradar responds with all relevant insights: bettor profile (confidence value, late bet score, marker score, bot score), event profile (event ratings, recommended live time delay), market profile (market rating, probabilities), and calculated values (fair and margin-adjusted cashout offers, plus the max potential win).
The operator’s algorithm applies custom business rules. For example:
If the bettor’s late bets score or bot score is high, the operator may apply higher live time delay or reduce the offer slightly.
If the event’s rating is low, the operator may delay or remove the cashout option.
The bettor accepts the operator’s tailored offer. Instead of calling placement, the operator executes the payout and then sends a
cashout-informto MTS.
This flow gives operators full flexibility of implementation: richer insights from Sportradar without giving up their own risk logic, while still ensuring liabilities are aligned.
Cashout Build Subscription vs. Auto Cashout
cashout-build-subscription and auto-cashout both use asynchronous monitoring, but they serve different purposes.
cashout-build-subscriptionrequests updated cash-out build values. The client decides whether and when to show the value and whether to submit placement or inform.auto-cashoutregisters a threshold condition, such as a take-win condition. MTS monitors the condition and notifies the client when the configured condition is fulfilled.
A cashout-build-reply is a current-value update. It is not a fulfilled auto-cashout notification.
Do not use cashout-build-subscription as a replacement for auto-cashout when the requirement is to monitor a bettor-defined threshold.
Cash-out integration guidelines
Selecting the cash-out operation
Transaction 3.0 supports three principal cash-out models:
cashout-buildcalculates current cash-out values and returns supporting information. It does not finalise a cash-out.cashout-placementsubmits a cash-out for validation and finalisation by MTS.cashout-informinforms MTS that the client has already executed a cash-out. It is intended for operator-controlled cash-out flows and does not provide the same risk validation ascashout-placement.
For a full-risk-delegation flow, use:
cashout-buildwhile the bettor is viewing an eligible ticket;display the selected cash-out value to the bettor;
submit
cashout-placementafter the bettor accepts the offer;pay the bettor only after an accepted placement response.
An accepted cashout-placement does not require a subsequent cashout-inform request.
For an operator-controlled flow, the client executes the cash-out locally and then sends cashout-inform to MTS. The inform operation updates MTS reporting and liabilities but does not delegate the cash-out validation to MTS.
Build and placement relationship
A cashout-build response does not create a server-side quote that must be referenced by a later cashout-placement request.
The build and placement requests should use:
the original
ticketId;the
ticketSignaturereturned in the original ticket-placement response.
The client does not need to reuse the cashoutId from the build request in the placement request. The signature returned in a cashout-build-reply is not currently used as an input to a subsequent placement request.
The client should nevertheless generate unique cashoutId and correlationId values and retain them for request tracking, response correlation, troubleshooting, and audit purposes. These identifiers are client-facing tracking identifiers; they are not the primary internal identifiers used by MTS to persist and process transactions.
Because a build result can become stale, clients should stop unnecessary build requests once the bettor initiates placement and should prevent another cash-out action for the same target until the placement response has been received.
Recommended build cadence
Start requesting cashout-build when the bettor opens or views the ticket and cash-out information is actually required. Stop requesting builds when the bettor leaves the ticket view.
Recommended client-side intervals are:
live tickets: 5 seconds;
pre-match tickets: 15 seconds;
when the client cannot determine whether the ticket is live: 10 seconds.
These are recommendations, not a replacement for the applicable request limits. Clients should avoid unnecessary polling and should not continue building indefinitely when no cash-out action can be taken.
A build value is a point-in-time calculation. It may become invalid or change before placement because of market probability changes, settlement, suspension, event state changes, or live-time-delay processing. There is no required delay between a build response and a placement request. However, the client must be prepared for placement to be rejected or for the acceptable cash-out value to differ when the market state has changed.
Values shown to the bettor
The build response may contain:
maxPayout;fairCashout;margin-adjusted
cashout.
The recommended value to display and use for a standard managed cash-out flow is the margin-adjusted value in the cashout response field.
The client must not assume that the value returned by the last build will always be accepted at placement. Placement performs the final validation against the current ticket and market state.
Cash-out scope
The following scopes are supported, subject to ticket eligibility and operator configuration:
full ticket cash-out;
partial ticket cash-out;
full bet cash-out;
partial bet cash-out.
A cash-out request targets a ticket or a complete bet. It does not target individual selections or legs inside an accumulator.
For a ticket containing multiple bets, one complete independent bet may be cashed out while the other bets remain open. An unsupported accumulator leg makes the affected bet ineligible and may also make the full ticket ineligible for managed cash-out.
A cash-out request supports one ticket or one bet only. Unrelated tickets or bets cannot be batched into a single cash-out request.
For a ticket cash-out, the maximum supported size is 50 bets, with a maximum of 100 selections per bet.
Ticket eligibility
Acceptance of the original ticket placement does not by itself guarantee eligibility for a later managed cash-out.
The ticket must also satisfy the applicable runtime and content conditions. Examples of conditions that can make a ticket ineligible include:
the ticket contains external content that MTS does not manage;
the ticket contains a mixture of supported and unsupported provider content;
the ticket or bet was cancelled;
the ticket or bet was already cashed out manually;
the cash-out request uses a currency that was not present on the original ticket;
incompatible ticket-level and bet-level cash-out scopes are mixed;
the requested target contains unsupported content.
MTS validates the managed content represented in the ticket, including content supplied through the OneFeed product. The client remains responsible for ensuring that its local ticket target corresponds exactly to the content represented in MTS.
Full or mixed external tickets do not currently support managed cash-out through cashout-build and cashout-placement. Such tickets may still be eligible for cashout-inform if the client calculates and executes the cash-out itself.
There is currently no separate public preflight service that guarantees cash-out eligibility before a build or placement request. Clients should use the ticket and runtime information available to them and handle a rejected build or placement response.
Partial cash-outs
For a partial cash-out, the request must contain cumulative values, not only the amount or percentage of the latest partial cash-out.
For example, if the first request cashes out 60% and the second request cashes out an additional 30%, the second request must contain:
percentage:0.9;the cumulative payout for the 90% already cashed out.
MTS treats the values in the latest request as the cumulative state and does not aggregate the values from previous requests. The same rule applies to cashout-placement and cashout-inform.
When the remaining portion is fully cashed out, use the complete-ticket or complete-bet cash-out structure as applicable. See the successive partial cash-out example.
Currency and rounding
The currency in a cash-out request must be one of the currencies present on the original ticket. MTS uses the ticket-acceptance exchange rates for supported ticket currencies. EUR is the base currency used for calculation.
Cash-out values support up to 8 decimal places. If the client submits fewer decimal places, it should round down rather than round to nearest. For example:
Only the cash stake is managed by MTS when a ticket contains multiple stake types. Use stakeOrigin when required to distinguish the cash-out value for a particular stake type. The field is optional and defaults to cash.
traceId is optional and may be used by the client to identify the source of a payout. The source field in a response indicates the origin of the payout.
Concurrent requests
Transaction 3.0 and the supported SDK allow multiple in-flight requests on the same WebSocket connection, including ticket and cash-out operations. The client must still correlate every response using correlationId and enforce its own per-ticket and per-bettor business rules.
Rate limits and error handling
Rate-limit identity
Transaction limits are applied per bookmaker (operatorId). The limits are shared across credentials, nodes, WebSocket connections, and other connections belonging to the same bookmaker.
The total request limit combines all supported operations, including ticket and cash-out operations. cashout-build may also be subject to a separate operation-specific limit.
The applicable values depend on the operator profile and environment. For the confirmed production profile:
cashout-build: 500 requests per second and 5,000 requests per minute.
Integration and other non-production environments use lower limits. Do not use production limits for integration load testing.
Higher limits may be requested. Requests to increase cashout-build limits should include information about the client's polling and request-handling efficiency. Contact Support to request increasing production rate limits.
The recommended client-side polling intervals for cashout-build do not apply to cashout-build-subscription in the same way, because subscription updates are delivered asynchronously. Clients must still respect the applicable operation and bookmaker rate limits when creating subscriptions.
Rate-limit response
When a rate limit is exceeded, MTS returns HTTP status code 429.
The client should:
stop or reduce unnecessary requests;
apply retry with backoff where a retry is appropriate;
contact Support if the limit is reached, particularly for ticket or production traffic;
avoid immediate repeated retries that could prolong throttling.
The client must implement the recommended build cadence and must not use repeated build requests as a substitute for local state management.
Cash-out build retry handling
A failed or timed-out cashout-build request does not change the ticket state. The client can issue a new build request, provided that it does not exceed the applicable limits or create unnecessary traffic.
A new build may return a different value because the ticket and market state may have changed.
Cash-out placement timeout or uncertain response
Placement changes the ticket state and may finalise a cash-out. If the client times out or loses the connection after sending a placement request, the result may be uncertain.
Do not automatically resubmit the placement request without first determining whether the original placement was processed. Contact Support for production incidents. Where appropriate, the client may issue a new build and inspect the settled percentage to help determine whether a cash-out has already taken place, but this is not a substitute for Support investigation.
Duplicate placement requests with the same requested amount are accepted according to the current MTS behaviour. Clients should still prevent duplicate bettor actions and retain all request identifiers for investigation.
Response correlation
Use correlationId to pair responses with requests. Store cashoutId, correlationId, ticketId, request timestamp, response timestamp, operation, status, and response code in client logs.
Last updated
Was this helpful?