> For the complete documentation index, see [llms.txt](https://docs.sportradar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportradar.com/transaction30api/api-description/ticket-json-format-description/cash-out-description-and-flow.md).
# 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 |
{% hint style="info" %}
`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.
{% endhint %}
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.
{% hint style="info" %}
**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.
{% endhint %}
### Cashout reason codes
Code
Reason message
101
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.
#### 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](/transaction30api/api-description/ticket-json-format-description/external-content-description.md) 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:
```
8.89514137 → 8.89
```
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.sportradar.com/transaction30api/api-description/ticket-json-format-description/cash-out-description-and-flow.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.