ComboBuilder ✨

Combine multiple selections into a single bet with correlated pricing

🆕 New — Now available for Football, Basketball, and Baseball.

Overview

The LSports ComboBuilder API enables operators to offer Combo Bet functionality — allowing bettors to combine multiple selections from a single fixture into one bet with a correlation-aware combined price.

Unlike naive parlay pricing that simply multiplies individual odds, the ComboBuilder engine accounts for statistical dependencies between selections (e.g., "Home Win" and "Over 2.5 Goals" are correlated events), producing a fair margined price that reflects joint probabilities.

Authentication

All ComboBuilder API endpoints require authentication via JWT access tokens. To obtain your credentials and authenticate, see the Authentication Guide.

Integration Workflow

The API consists of two endpoints designed to be used together:

1. Resolve market dependencies — For each selection the end user wants to include, call /v1/betbuilder/markets to determine which market data the pricing engine requires. Markets often have dependencies - for example, pricing a "Player Total Shots" selection may require you to also provide "Shots on Target" and "Assists" data in the same request. This endpoint tells you exactly what to supply.

2. Build the combined price — Call /v1/betbuilder with the fixture's market data (as determined in step 1), the user's selections, and participant/player information. The API returns a single combined decimal odds value along with metadata indicating which selections are required vs. redundant.

Coverage: ComboBuilder is available for all Football leagues. No coverage check is required.

Key Principle

The operator is responsible for supplying the underlying market odds data to the pricing engine. The ComboBuilder does not source odds - it derives the combined price from the data you provide. The richer and more complete the market data you supply (more lines, more periods), the more accurate the combined pricing will be.

Refer to the full API specification below for request/response schemas, supported market keys, period definitions, and worked examples for Football.

Derive combined bet price

post

Calculates a margined combined price for two or more selections on a fixture.

The markets object provides the probabilistic model data the pricing engine needs to derive prices.

Minimum 2 selections required — single selections are not supported.

Market key reference

Key	Used for
goals	All standard markets (1X2, totals, handicaps, goalscorer)
shots	Player total shots
shotsOnTarget	Player shots on target
assists	Player assists
passes	Player passes
tackles	Player tackles
cards	Player/team cards
corners	Corner kick markets

Period keys

Period key	Meaning
RT	Regulation time (full match)
H1	First half
H2	Second half

---

Market key structure

Each entry in markets is a market key → period key → odds data. Example shape:

"markets": {
  "{marketKey}": {
    "{periodKey}": {
      "europeanHandicaps": { ... },
      "asianHandicaps":    { ... },
      "asianTotals":       { ... },
      "nthPlayers":        { ... },
      "asianPlayerTotals": { ... }
    }
  }
}

goals (primary market — required)

• Periods: RT, H1, H2

• Sub-fields: europeanHandicaps, asianHandicaps, asianTotals, nthPlayers, correctScore, europeanFirstTos

• nthPlayers must include all players from both teams under keys "*" (anytime), "1" (first scorer), "-1" (last scorer)

• Both europeanHandicaps and asianTotals are required in goals.RT for the pricing model to calibrate

shots, shotsOnTarget, assists, passes, tackles, cards

• Periods: RT

• Sub-fields: asianPlayerTotals (keyed by player ID, e.g. "101")

corners

• Periods: RT, H1

• Sub-fields: asianTotals

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Bearer token issued by the authentication provider (Frontegg). Include the token in the Authorization header as Bearer <token>.

Header parameters

customerIdintegerRequired

Customer ID. Must match the tenantId claim in the JWT token. Used for authorization — the customer must be registered for BetBuilder access.

Example: 12345

Body

application/json

sportIdinteger · enumRequired

LSports sport ID

Example: 6046Possible values:

leagueIdinteger · nullableOptional

LSports league/tournament ID (optional for Football).

Example: 218

fixtureIdinteger · nullableOptional

LSports fixture ID. Each request must use a unique value so the engine treats it as an independent event. Reusing the same ID across requests can cause state caching issues on the engine side.

Example: 100001

eventIdstring · nullableOptional

Optional external event reference ID.

viewIdstring · nullableOptional

Optional view/session reference ID.

Responses

200

Combined bet price successfully derived

application/json

correlationIdstring · nullableOptional

Internal correlation ID for tracing.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

pricenumber · doubleOptional

Combined margined decimal odds for all selections. Capped at 450.

Example: 4.6

requiredSelectionsinteger[] · nullableOptional

1-based indices of selections that are required for the bet to be valid.

Example: [1,2]

400

Bad request — missing required fields or invalid format

application/json

401

Unauthorized — missing or invalid JWT Bearer token

403

Forbidden — the customer is not authorized for BetBuilder. Returned when the customerId header is missing/invalid or the customer does not have BetBuilder access.

application/json

422

Unprocessable Entity — pricing engine cannot process the request.

Error Types:

errorCode	errorType	Description
1001	UnprocessableEntity	Missing source markets or state data to calculate the selection
1002	InvalidBetslip	The combination of selections on the betslip is invalid (e.g., mutually exclusive)
1003	UnwinnableBet	The combination of selections results in zero-win probability
1004	CalculationError	An error occurred while calculating the betslip

application/json

500

Internal server error — unexpected error occurred

application/json

501

Not Implemented — selection type is not supported

application/json

502

Bad Gateway — failed to connect to pricing service

application/json

503

Service Unavailable — pricing service is temporarily unavailable

application/json

504

Gateway Timeout — pricing service request timed out

application/json

post

/v1/betbuilder

HTTPcURLJavaScriptPython

POST /v1/betbuilder HTTP/1.1
Host: bet-builder-gw.lsports.eu
Authorization: Bearer YOUR_SECRET_TOKEN
customerId: 1
Content-Type: application/json
Accept: */*
Content-Length: 1130

{
  "sportId": 6046,
  "leagueId": 218,
  "fixtureId": 10001,
  "participants": [
    {
      "id": 1,
      "name": "Liverpool",
      "players": [
        {
          "id": 101,
          "name": "Salah"
        },
        {
          "id": 102,
          "name": "Firmino"
        }
      ]
    },
    {
      "id": 2,
      "name": "Chelsea",
      "players": [
        {
          "id": 201,
          "name": "Palmer"
        },
        {
          "id": 202,
          "name": "Jackson"
        }
      ]
    }
  ],
  "selections": [
    {
      "marketId": 1,
      "outcome": "1"
    },
    {
      "marketId": 2,
      "outcome": "O",
      "line": 2.5
    }
  ],
  "markets": {
    "goals": {
      "RT": {
        "europeanHandicaps": {
          "0": {
            "1": 2.45,
            "2": 3.25,
            "X": 3.2
          },
          "1": {
            "1": 1.364,
            "2": 6.25,
            "X": 4.333
          },
          "-1": {
            "1": 4.75,
            "2": 1.55,
            "X": 3.8
          }
        },
        "asianTotals": {
          "2": {
            "O": 1.571,
            "U": 2.35
          },
          "2.5": {
            "O": 2.05,
            "U": 1.75
          },
          "3.5": {
            "O": 3.7,
            "U": 1.25
          },
          "1.5": {
            "O": 1.364,
            "U": 3.1
          }
        },
        "nthPlayers": {
          "1": {
            "101": 8,
            "102": 11.5,
            "201": 15,
            "202": 18.5
          },
          "*": {
            "101": 3.2,
            "102": 4.4,
            "201": 5.6,
            "202": 6.8
          },
          "-1": {
            "101": 8,
            "102": 11.5,
            "201": 15,
            "202": 18.5
          }
        },
        "europeanFirstTos": {
          "0": {
            "Yes": 1.75,
            "No": 2.05
          }
        }
      },
      "H1": {
        "europeanHandicaps": {
          "0": {
            "1": 3,
            "2": 3.55,
            "X": 2
          }
        },
        "asianTotals": {
          "1": {
            "O": 2,
            "U": 1.75
          },
          "0.5": {
            "O": 1.45,
            "U": 2.625
          }
        }
      }
    },
    "shotsOnTarget": {
      "RT": {
        "asianPlayerTotals": {
          "101": {
            "0.5": {
              "O": 1.25,
              "U": 2.35
            },
            "1.5": {
              "O": 2.35,
              "U": 1.55
            }
          },
          "102": {
            "0.5": {
              "O": 1.7,
              "U": 2.05
            }
          },
          "201": {
            "0.5": {
              "O": 1.5,
              "U": 2.4
            }
          },
          "202": {
            "0.5": {
              "O": 1.9,
              "U": 1.8
            }
          }
        }
      }
    }
  }
}

Football 1 — Home Win + Over 2.5 GoalsFootball 2 — Away Win + Over 2.5 GoalsFootball 3 — Anytime Goalscorer (Salah) + Home WinFootball 4 — Two Players to Score + Over 2.5 GoalsFootball 5 — Player Shots on Target + Player Assists + Away WinFootball 6 — Both Teams to Score + Over 2.5 GoalsFootball 7 — H1 Home Win + Full Time Home Win + Over 2.5Football 8 — Double Chance (Home or Draw) + Under 2.5Football 9 — Correct Score 2:1 + Home WinFootball 10 — Complex: Goalscorer + BTTS + Over 2.5 + Home Win (4-leg)Football 11 — Complex: Player SOT + Away Goalscorer + Over 2.5 + Asian Handicap -1 (4-leg)Football 12 — Complex: Away Win + BTTS + Under 3.5 Goals + Over 9.5 Corners (4-leg cross-market)Football 13 — Complex: Over 3.5 Cards + Over 9.5 Corners + BTTS (stats parlay)Football 14 — Complex: 2x Goalscorer + SOT + Assists + Home Win (5-leg player prop parlay)

{
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "price": 4.6,
  "requiredSelections": [
    1,
    2
  ],
  "selections": [
    {
      "bet": {
        "marketId": 1,
        "outcome": "1",
        "line": null,
        "playerId": null,
        "period": null
      },
      "isRequired": true
    },
    {
      "bet": {
        "marketId": 2,
        "outcome": "O",
        "line": 2.5,
        "playerId": null,
        "period": null
      },
      "isRequired": true
    }
  ]
}

Get supported markets for a sport

post

Returns the list of LSports markets supported by BetBuilder for Football, together with any dependent markets required to price them.

For example, the shots market (ID 1397) depends on shotsOnTarget and assists being provided in the same request for the pricing model to calibrate correctly.

Authorizations

BearerAuth

AuthorizationstringRequired

JWT Bearer token issued by the authentication provider (Frontegg). Include the token in the Authorization header as Bearer <token>.

Header parameters

customerIdintegerRequired

Customer ID. Must match the tenantId claim in the JWT token. Used for authorization — the customer must be registered for BetBuilder access.

Example: 12345

Body

application/json

sportIdinteger · enumRequired

LSports sport ID

Example: 6046Possible values:

marketIdinteger · nullableOptional

Optional filter — return data for a single market only.

Example: 1397

Responses

200

List of supported markets with dependencies

application/json

401

Unauthorized — missing or invalid JWT Bearer token

403

Forbidden — the customer is not authorized for BetBuilder. Returned when the customerId header is missing/invalid or the customer does not have BetBuilder access.

application/json

post

/v1/betbuilder/markets

HTTPcURLJavaScriptPython

POST /v1/betbuilder/markets HTTP/1.1
Host: bet-builder-gw.lsports.eu
Authorization: Bearer YOUR_SECRET_TOKEN
customerId: 1
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "sportId": 6046
}

{
  "result": [
    {
      "sport": {
        "id": 6046,
        "name": "Football"
      },
      "market": {
        "id": 1397,
        "name": "Player Total Shots"
      },
      "dependedMarketIds": [
        {
          "id": 3201,
          "name": "Player Shots On Target"
        },
        {
          "id": 2734,
          "name": "Player Assists"
        }
      ]
    }
  ]
}