> 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/betlink-integration/backend-integration/bet-placement-endpoint.md).

# Bet Placement Endpoint

Path: {operator-env-url}/bet

Bet placement involves the submission of a betslip that contains one or more single bets. As visible in the Request Parameters table below, an array of single bets exists for the 'bets' parameter. When bet placement calls are made to this endpoint, the operator needs to take the following steps:

* validate the user session by looking up the user session based on userId and sessionToken and ensuring that session details are correct and not expired
* confirm that the user has a sufficient balance to cover the sum total of all the individual bet stakes
* confirm that the user is able to place each bet in light of any regulatory restrictions (could be cool down periods, max stakes, max liability per market type etc.)
* upon successfully completing all relevant checks, store all bet information for each bet in the bets array against the userId with a status equivalent to 'pending' to indicate that the bet is awaiting result. A `potentialPayout` amount should be calculated by multiplying the decimalPrice field by the stake. This should be saved alongside the bet to facilitate bet resulting. Here is the formula for clarity:

`potentialPayout = (stake * decimalPrice)`

* respond with a response matching the 'Response Parameters' schema as detailed below
* or alternatively.. upon unsuccessfully completing all relevant check, store none of the bets in the bet placement call and respond with a relevant error response, as detailed below

### Request Parameters

type: `POST`\
content-type: `application/json`

#### Idempotency

Request will contain a header `X-Idempotency-Key` in the form of a UUID string. See 'Idempotency' section for more information.

<table><thead><tr><th width="194">Parameter</th><th width="179">Type</th><th width="111">Required?</th><th>Example</th></tr></thead><tbody><tr><td>requestId</td><td>String/UUID</td><td>Yes</td><td>92e02ae9-a2a3-48e2-af0e-940aec4bbcfb</td></tr><tr><td>userId</td><td>String</td><td>Yes</td><td>user123</td></tr><tr><td>sessionToken</td><td>String</td><td>Yes</td><td>0bJV7oLNI0iMFl3rlomqQQ==</td></tr><tr><td>timestamp</td><td>String (epoch)</td><td>Yes</td><td>1640995200000</td></tr><tr><td>bets</td><td>Array &#x3C;BetDetails></td><td>Yes</td><td></td></tr></tbody></table>

### Response Parameters

accepts: `application/json`

<table><thead><tr><th>Parameter</th><th width="181">Type</th><th width="112">Required?</th><th></th></tr></thead><tbody><tr><td>requestId</td><td>String/UUID</td><td>Yes</td><td>Matches request's requestId</td></tr><tr><td>userId</td><td>String</td><td>Yes</td><td></td></tr><tr><td>sessionToken</td><td>String</td><td>Yes</td><td>Original or refreshed</td></tr><tr><td>timestamp</td><td>String (epoch)</td><td>Yes</td><td>Response timestamp</td></tr><tr><td>status</td><td>String ("PLACED")</td><td>Yes</td><td></td></tr><tr><td>bets</td><td>Array &#x3C;BetDetails></td><td>Yes</td><td></td></tr></tbody></table>

### Error Response

accepts: `application/json`

| Parameter    | Type               | Required?                             |
| ------------ | ------------------ | ------------------------------------- |
| status       | String ("FAILURE") | Yes                                   |
| errorCode    | String             | Yes                                   |
| errorMessage | String             | No                                    |
| failedBets   | Array \<FailedBet> | No (Except for INVALID\_STAKE errors) |

#### Errors

| Error Code             | Http Status |
| ---------------------- | ----------- |
| INVALID\_USER          | 400         |
| INVALID\_BET\_DETAILS  | 400         |
| INVALID\_STAKE         | 400         |
| INSUFFICIENT\_FUNDS    | 400         |
| USER\_BLOCKED          | 400         |
| MISSING\_PARAMETER     | 400         |
| INVALID\_SESSION       | 401         |
| AUTHENTICATION\_FAILED | 403         |
| GENERAL\_EXCEPTION     | 500         |
| REQUEST\_TIMED\_OUT    | 503         |

***

## Model Definitions

### BetDetails

<table><thead><tr><th>Parameter</th><th width="158">Type</th><th>Required?</th></tr></thead><tbody><tr><td>betId</td><td>String/UUID</td><td>Yes</td></tr><tr><td>sportId</td><td>String</td><td>Yes</td></tr><tr><td>sportName</td><td>String</td><td>Yes</td></tr><tr><td>sportDisplayName</td><td>String</td><td>Yes</td></tr><tr><td>eventId</td><td>String</td><td>Yes</td></tr><tr><td>eventAltId</td><td>String</td><td>No</td></tr><tr><td>eventName</td><td>String</td><td>Yes</td></tr><tr><td>eventDisplayName</td><td>String</td><td>Yes</td></tr><tr><td>eventStage</td><td>String/Stage</td><td>Yes</td></tr><tr><td>competitionId</td><td>String</td><td>Yes</td></tr><tr><td>competitionName</td><td>String</td><td>Yes</td></tr><tr><td>competitionDisplayName</td><td>String</td><td>Yes</td></tr><tr><td>marketTypeId</td><td>String</td><td>Yes</td></tr><tr><td>marketId</td><td>String</td><td>Yes</td></tr><tr><td>marketName</td><td>String</td><td>Yes</td></tr><tr><td>marketDisplayName</td><td>String</td><td>Yes</td></tr><tr><td>marketStage</td><td>String/Stage</td><td>Yes</td></tr><tr><td>selectionId</td><td>String</td><td>Yes</td></tr><tr><td>selectionName</td><td>String</td><td>Yes</td></tr><tr><td>selectionDisplayName</td><td>String</td><td>Yes</td></tr><tr><td>decimalPrice</td><td>Decimal/Double</td><td>Yes</td></tr><tr><td>stake</td><td>Decimal/Double</td><td>Yes</td></tr></tbody></table>

{% hint style="info" %}
`eventAltId` is an optional field that may contain an alternate eventId (eg a DDE id for golf bets)
{% endhint %}

### FailedBet

<table><thead><tr><th width="248">Parameter</th><th width="174">Type</th><th>Required?</th></tr></thead><tbody><tr><td>betId</td><td>String/UUID</td><td>Yes</td></tr><tr><td>sportId</td><td>String</td><td>Yes</td></tr><tr><td>eventId</td><td>String</td><td>Yes</td></tr><tr><td>marketId</td><td>String</td><td>Yes</td></tr><tr><td>selectionId</td><td>String</td><td>Yes</td></tr><tr><td>reason</td><td>BetFailureReason</td><td>Yes</td></tr></tbody></table>

#### BetFailureReason

<table><thead><tr><th width="248">Parameter</th><th width="174">Type</th><th>Required?</th></tr></thead><tbody><tr><td>maxStake</td><td>Decimal/Double</td><td>No</td></tr><tr><td>minStake</td><td>Decimal/Double</td><td>No</td></tr></tbody></table>

{% hint style="info" %}
the stake value returned within **BetFailureReason** should be the value of the limit breached
{% endhint %}

#### Stage

| Parameter Variables |
| ------------------- |
| IN\_PLAY            |
| PRE\_PLAY           |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sportradar.com/betlink-integration/backend-integration/bet-placement-endpoint.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
