Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

Operation
Purpose
Validation / Who Executes Logic
When to Use

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

cashout-build-subscription and auto-cashout are monitoring operations. Neither operation finalises a cash-out by itself.

When the client receives an updated cash-out value or a fulfilled condition, it must still use the applicable finalisation flow:

  • cashout-placement when MTS should validate and finalise the cash-out;

  • cashout-inform when the client executes the cash-out locally and informs MTS afterwards and after the finalized auto-cashout notification is sent to the operator.

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.

Note

  • To avoid potential latency abuses, it is recommended that at least 7 or 8 seconds of delay are added on the client's side before sending a cashout-inform request (cashout-build can be used).

  • By default, the cashout functionality is turned off on the MTS side. If your platform supports cashout and you need the cashout features activated in MTS, please get in touch with the MTS OAM team or an MTS Client Integration Engineer during the integration process.

Cashout reason codes

Code
Reason message

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.

  1. The operator immediately starts calling the cashout-build operation 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).

  2. 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.

  3. The bettor accepts the displayed offer and presses the "Cash Out" button, sending full or partial cashout request. The operator now sends a cashout-placement request 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.

  4. 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:

  1. The client sends a cashout-build-subscription request for an eligible ticket or bet.

  2. MTS validates and registers the subscription.

  3. MTS monitors the subscribed target and processes relevant updates.

  4. MTS sends a cashout-build-reply after each applicable recalculation.

  5. The client displays or uses the latest returned value.

  6. The client finalises the cash-out using either:

    • cashout-placement, if MTS should perform the final validation and execution; or

    • cashout-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:

  1. The client calculates and displays a cash-out offer.

  2. The bettor accepts the offer.

  3. The client executes the payout locally.

  4. The client sends cashout-inform to 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.

  1. 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).

  2. 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.

  3. The bettor accepts the operator’s tailored offer. Instead of calling placement, the operator executes the payout and then sends a cashout-inform to 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-subscription requests updated cash-out build values. The client decides whether and when to show the value and whether to submit placement or inform.

  • auto-cashout registers 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-build calculates current cash-out values and returns supporting information. It does not finalise a cash-out.

  • cashout-placement submits a cash-out for validation and finalisation by MTS.

  • cashout-inform informs 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 as cashout-placement.

For a full-risk-delegation flow, use:

  1. cashout-build while the bettor is viewing an eligible ticket;

  2. display the selected cash-out value to the bettor;

  3. submit cashout-placement after the bettor accepts the offer;

  4. 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 ticketSignature returned 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.

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:

  1. stop or reduce unnecessary requests;

  2. apply retry with backoff where a retry is appropriate;

  3. contact Support if the limit is reached, particularly for ticket or production traffic;

  4. 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?