Skip to content

Bet Builder Integration Guide

What is Bet Builder?

Bet Builder is a feature that allows users to create customized bets by combining multiple markets within a single sports event. It provides players with the flexibility to select outcomes from the same match and combine them into a single bet with dynamically calculated odds.

Key Characteristics of Bet Builder

  • Customizable Bets: Users can select multiple markets from a single event, such as the final score, total goals, or player-specific outcomes.
  • Dynamic Odds Calculation: Odds are calculated based on the dependencies between selected markets. For instance, betting on "Team A to win" and "Team A to score 2+ goals" will factor in the correlation between these outcomes.
  • Single Bet Type: Even when combining multiple markets, Bet Builder bets are treated as a Single bet, as they relate to one sport event.
  • Enhanced User Experience: Bet Builder allows users to tailor bets to their insights and predictions for a specific game.

Difference Between Bet Builder and Express (Combo) Bets?

Bet Builder and Express (Combo) bets differ in their scope, odds calculation, and use cases. The table below highlights the key differences:

Feature Bet Builder Express (Combo)
Event Scope Combines multiple markets within one match. Combines bets from different matches.
Bet Type Single bet Combo/Express
Odds Calculation Adjusted for market dependencies within one match. Multiplies independent odds from each match.
Use Case Detailed insights into a single event (e.g. football). Broader strategy covering multiple events.

Examples

Bet Builder (Single Bet)

Imagine a football match between Team A and Team B. User selects:

  • Team A to win (odds: 1.50)
  • Over 2.5 goals (odds: 2.00)

The combined Bet Builder odds might be calculated as 3.20, reflecting the correlation between these outcomes.

Express Bet (Combo Bet)

A user combines:

  • Team A to win their match (odds: 1.50)
  • Team B to win a different match (odds: 2.00)

The total odds for this Combo Bet would be 3.00 (1.50 × 2.00), since the outcomes are independent.

Mixing Bet Builder with Combo Bets

Bet Builder can be part of a Combo Bet when combined with other bets from different matches. For example:

  • A Bet Builder for Match 1 (odds: 3.20)
  • A Single Bet for Match 2 (odds: 2.50)

The final odds for the Express Bet would be 8.00 (3.20 × 2.50).

Detecting Bet Builder Availability for a Sport Event

To determine if the Bet Builder feature is available for a specific sport event, follow these steps:

1. Activation in STM

Before Bet Builder can be available for any event, DATA.BET admins must enable this feature in the STM system.
For details on working with STM, refer to the STM Overview.

If Bet Builder is not enabled in STM, it will not appear in the odds feed, regardless of any other configuration.

2. Detecting Availability via Odds Feed

When the Bet Builder feature is available for a particular sport event, users will receive a dedicated log in the odds feed:
app.data.bet/bet-builder.

This log includes the key enabled with a boolean value, indicating whether Bet Builder is active for the event.

Example Odds Feed Log

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "version": "22h2KoCl1uu000004gfQS1",
  "sport_id": "football",
  "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
  "timestamp_ns": "1692950400000000000",
  "event_type": "extensions_updated",
  "payload": {
    "app.data.bet/bet-builder": {
      "enabled": true
    }
  }
}

Using the Bet Builder

Calculate Bet Builder

Before a user see available selections, a POST request to /bet-builder/calculate must be sent to the MTS to define the scope of available markets for the Bet Builder. This request must also be triggered after each selection is added to ensure that the odds are recalculated and up-to-date before the bet is placed.

1
2
3
4
5
6
7
8
9
curl -X POST "https://{mts-server}/bet-builder/calculate" \
--header "Content-Type: application/json" \
--crt tls.crt \
--key tls.key \
--data '{
    "player_id": "player123",
    "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
    "selections": []
}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
curl -X POST 'https://{mts-server}/bet-builder/calculate' \
--header "Content-Type: application/json" \
--crt tls.crt \
--key tls.key \
--data '{
  "player_id": "player123",
  "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d472",
  "selections": [
    {
      "market_id": "20",
      "odd_id": "1"
    },
    {
      "market_id": "10m1h_5",
      "odd_id": "2"
    }
  ]
}'

The response will contain the available markets with the updated odds and total value for the selections. Each market includes the market id, the status, and an array of odds that are available for that market

Calculate Bet with bet_builder_selections (optional in the advisory mode)

Before placing a bet, it is important to calculate the bet for the following reason:

  • Check for Restrictions: The calculation will verify whether any restrictions apply to the bet, such as limits on stake, restrictions on certain types of bets, or any other platform-specific rules. This helps to ensure that the bet complies with all applicable constraints before proceeding.

Important

You must populate $.bet_builder_selections.selections.value with the original_value of an odd (not the total Bet Builder value), which can be obtained from either the feed or the /bet-builder/calculate response.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
curl -X POST "https://{mts-server}/bets/calculate" \
  --header "Content-Type: application/json" \
  --crt tls.crt \
  --key tls.key \
  --data '{
    "bet_id": "m7k6BN-4yRaiEtl+YxmvSGOiUXEEF9IAAA/iqwAQ",
    "bet_type": {
      "code": 0,
      "size": [1]
    },
    "stake": {
      "value": "100",
      "currency_code": "USD"
    },
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      }
    ],
    "player_id": "player123",
    "client_ip": "192.168.1.1",
    "country_code": "US",
    "created_at": "2025-01-28T14:00:00Z",
    "odd_accept_strategy": 1
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
curl -X POST 'https://{mts-server}/bets/calculate' \
  --header "Content-Type: application/json" \
  --crt tls.crt \
  --key tls.key \
  --data '{
    "bet_id": "m7k6BN-4yRaiEtl+YxmvSGOiUXEEF9IAAA/iqwAQ",
    "bet_type": {
      "code": 1,
      "size": [2]
    },
    "stake": {
      "value": "50",
      "currency_code": "USD"
    },
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      }
    ],
    "selections": [
      {
        "sport_event_id": "2d53f7c8-27b2-4876-b983-18a917e62c5a",
        "market_id": "5",
        "odd_id": "3",
        "value": "2.00"
      }
    ],
    "player_id": "player123",
    "client_ip": "192.168.1.1",
    "country_code": "US",
    "created_at": "2025-01-28T14:00:00Z",
    "odd_accept_strategy": 1
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
curl -X POST 'https://{mts-server}/bets/calculate' \
  --header "Content-Type: application/json" \
  --crt tls.crt \
  --key tls.key \
  --data '{
    "bet_id": "m7k6BN-4yRaiEtl+YxmvSGOiUXEEF9IAAA/iqwAQ",
    "bet_type": {
      "code": 1,
      "size": [2]
    },
    "stake": {
      "value": "50",
      "currency_code": "USD"
    },
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      },
      {
        "sport_event_id": "7a927dac-e3ac-4319-9a2f-c5c7c2b320f1",
        "value": "2.00",
        "selections": [
          {
            "sport_event_id": "7a927dac-e3ac-4319-9a2f-c5c7c2b320f1",
            "market_id": "1",
            "odd_id": "2",
            "value": "1.80"
          },
          {
            "sport_event_id": "7a927dac-e3ac-4319-9a2f-c5c7c2b320f1",
            "market_id": "2",
            "odd_id": "2",
            "value": "1.80"
          }
        ]
      }
    ],
    "player_id": "player123",
    "client_ip": "192.168.1.1",
    "country_code": "US",
    "created_at": "2025-01-28T14:00:00Z",
    "odd_accept_strategy": 1
  }'

When using the /bets/calculate endpoint, you will receive the details of the bet, including the calculated odds and any restrictions that apply. It is crucial that clients use the calculated value from the bet_builder_selections section of the response for the actual place bet request.

Response example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "calculated_bet": {
    "type": {
      "code": 1,
      "size": [3]
    },
    "selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "market_id": "1",
        "odd_id": "1",
        "value": "1.50"
      },
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "market_id": "2",
        "odd_id": "1",
        "value": "1.50"
      }
    ],
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      }
    ]
  },
  "restrictions": [
    {
      "type": "max_bet",
      "context": {"max_bet": "443.34"}
    }
  ]
}

Place request

Once the user is satisfied with their selections in the Bet Builder, they need to place the bet by making a request to the /bets (/bets/advisory for advisory) endpoint of the MTS. This request must include the bet_builder_selections in the payload.

Important

You must fill $.bet_builder_selections.selections.value by by original_value(not value) field, from /bet-builder/calculate response.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
curl -X POST "https://{mts-server}/bets" \
--header "Content-Type: application/json" \
--crt tls.crt \
--key tls.key \
--data '{
    "bet_id": "m7k6BN-4yRaiEtl+YxmvSGOiUXEEF9IAAA/iqwAQ",
    "bet_type": {
      "code": 0,
      "size": [1]
    },
    "stake": {
      "value": "100",
      "currency_code": "USD"
    },
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      }
    ],
    "player_id": "player123",
    "client_ip": "192.168.1.1",
    "country_code": "US",
    "created_at": "2025-01-28T14:00:00Z",
    "odd_accept_strategy": 1
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
curl -X POST 'https://{mts-server}/bets' \
--header "Content-Type: application/json" \
--crt tls.crt \
--key tls.key \
--data '{
    "bet_id": "m7k6BN-4yRaiEtl+YxmvSGOiUXEEF9IAAA/iqwAQ",
    "bet_type": {
      "code": 1,
      "size": [2]
    },
    "stake": {
      "value": "50",
      "currency_code": "USD"
    },
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      }
    ],
    "selections": [
      {
        "sport_event_id": "2d53f7c8-27b2-4876-b983-18a917e62c5a",
        "market_id": "5",
        "odd_id": "3",
        "value": "2.00"
      }
    ],
    "player_id": "player123",
    "client_ip": "192.168.1.1",
    "country_code": "US",
    "created_at": "2025-01-28T14:00:00Z",
    "odd_accept_strategy": 1
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
curl -X POST 'https://{mts-server}/bets' \
--header "Content-Type: application/json" \
--crt tls.crt \
--key tls.key \
--data '{
    "bet_id": "m7k6BN-4yRaiEtl+YxmvSGOiUXEEF9IAAA/iqwAQ",
    "bet_type": {
      "code": 1,
      "size": [2]
    },
    "stake": {
      "value": "50",
      "currency_code": "USD"
    },
    "bet_builder_selections": [
      {
        "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
        "value": "1.55",
        "selections": [
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "1",
            "odd_id": "1",
            "value": "1.50"
          },
          {
            "sport_event_id": "e688b996-eaf9-40f2-b6e6-325d99c4d473",
            "market_id": "2",
            "odd_id": "1",
            "value": "1.50"
          }
        ]
      },
      {
        "sport_event_id": "7a927dac-e3ac-4319-9a2f-c5c7c2b320f1",
        "value": "2.00",
        "selections": [
          {
            "sport_event_id": "7a927dac-e3ac-4319-9a2f-c5c7c2b320f1",
            "market_id": "1",
            "odd_id": "2",
            "value": "1.80"
          },
          {
            "sport_event_id": "7a927dac-e3ac-4319-9a2f-c5c7c2b320f1",
            "market_id": "2",
            "odd_id": "2",
            "value": "1.80"
          }
        ]
      }
    ],
    "player_id": "player123",
    "client_ip": "192.168.1.1",
    "country_code": "US",
    "created_at": "2025-01-28T14:00:00Z",
    "odd_accept_strategy": 1
  }'

Settle Bet Builder Bets

To settle odds for bet builder bets in your sportsbook, you must ensure that your system listens for markets_updated logs from the odds feed. These updates provide the most recent odd statuses, which are essential for accurate bet builder calculation and settlement.

Bet Calculation Rules

  1. Selection Status Evaluation:
    Assign an odd status (won, lost, refunded, etc.) to each selection in the bet builder.

    • If at least one selection is lost and no other selection is voided or refunded, the entire Bet Builder bet is considered lost.
    • If all selections are won, the bet builder is considered won.

  2. Handling Voided or Refunded Selections:

    • If any selection in the bet builder is voided or refunded, the entire bet builder bet is refunded — it cannot be partially settled.
    • If one selection is lost and another is voided or refunded, the entire bet is refunded, regardless of evaluation order.
    • This differs from regular combo bets, where a voided selection would normally be removed and the odds recalculated.

  3. Half-Win/Half-Loss Odd Statuses (Asian Markets) Not Applicable:
    Bet builder bets do not support half-win or half-loss statuses and asian markets in general. Each selection must be fully settled as won, lost, or refunded.

  4. Odds in Bet Builder Selections:
    These odds cannot be multiplied to calculate the total bet builder odds.