Bet Builder

Combine multiple selections into a single bet with correlated pricing

Overview

The LSports BetBuilder API enables operators to offer Bet Builder 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 BetBuilder 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 Bet Builder API endpoints require authentication via JWT access tokens. To obtain your credentials and authenticate, see the Authentication Guide.

Integration Workflow

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

1. Discover coverage — Call /v1/betbuilder/leagues to retrieve the supported leagues per sport and their format configuration (available periods, extra time support, etc.). This tells you which fixtures are eligible for Bet Builder.

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

3. Build the combined price — Call /v1/betbuilder with the fixture's market data (as determined in step 2), 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.

Key Principle

The operator is responsible for supplying the underlying market odds data to the pricing engine. The BetBuilder 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 across all three sports.

Derive combined bet price

post

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

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

Market key reference by sport

Key	Sport	Used for
goals	Football	All standard markets (1X2, totals, handicaps, goalscorer)
shots	Football	Player total shots
shotsOnTarget	Football	Player shots on target
assists	Football	Player assists
passes	Football	Player passes
tackles	Football	Player tackles
cards	Football	Player cards
fouls	Football	Player fouls
corners	Football	Corner kick markets
points	Basketball	All standard markets + player points
assists	Basketball	Player assists
rebounds	Basketball	Player rebounds
steals	Basketball	Player steals
blocks	Basketball	Player blocks
points{value=3}	Basketball	Player 3-pointers made
points	American Football	All standard markets (moneyline, totals, spread)
yards	American Football	All player/team yards markets
touchdowns	American Football	All player/team touchdown markets

Period keys

Sport	Period key	Meaning
Football	RT	Regulation time (full match)
Football	H1	First half
Football	H2	Second half
Basketball / AMFO	*	Full game (incl. overtime)
Basketball / AMFO	H1	First half
Basketball / AMFO	Q1–Q4	Individual quarters

---

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": { ... }
    }
  }
}

Football — goals

• 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)

Football — shots, shotsOnTarget, assists, passes, tackles, cards, fouls

• Periods: RT

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

Football — corners

• Periods: RT, H1

• Sub-fields: asianTotals

Basketball — points

• Periods: *, H1, Q1–Q4

• Sub-fields: asianHandicaps, asianTotals, asianPlayerTotals

Basketball — assists, rebounds, steals, blocks, points{value=3}

• Periods: *

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

• All player-stat keys must be sent together in the same request

American Football — points

• Periods: *, H1, Q1–Q4

• Sub-fields: asianHandicaps, asianTotals

American Football — yards

• Periods: *

• Sub-fields: asianPlayerPasses (passing yards), asianPlayerRushes (rushing yards), asianPlayerReceives (receiving yards), asianPlayerRushReceives (combined rush + receive)

American Football — touchdowns

• Periods: *

• Sub-fields: asianPlayerTotals (total TDs), asianPlayerPasses (passing TDs)

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. Required for Basketball and American Football to select the correct pricing model format.

Known values

League	ID
NBA	64
WNBA	761
NCAA Basketball	4045
Euroleague	33249
NFL	75
NCAA Football	32505

Example: 64

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.

Example: 3.45

requiredSelectionsinteger[] · nullableOptional

Indices of selections that are required for the bet to be valid.

Example: [0,1]

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: 1793

{
  "sportId": 6046,
  "leagueId": 218,
  "fixtureId": 10001,
  "participants": [
    {
      "id": 1,
      "name": "Liverpool",
      "players": [
        {
          "id": 101,
          "name": "Salah"
        },
        {
          "id": 102,
          "name": "Firmino"
        },
        {
          "id": 103,
          "name": "Nunez"
        },
        {
          "id": 104,
          "name": "Alexander-Arnold"
        },
        {
          "id": 105,
          "name": "Robertson"
        },
        {
          "id": 106,
          "name": "Gravenberch"
        },
        {
          "id": 107,
          "name": "Mac Allister"
        },
        {
          "id": 108,
          "name": "Szoboszlai"
        },
        {
          "id": 109,
          "name": "Van Dijk"
        },
        {
          "id": 110,
          "name": "Konate"
        }
      ]
    },
    {
      "id": 2,
      "name": "Chelsea",
      "players": [
        {
          "id": 201,
          "name": "Palmer"
        },
        {
          "id": 202,
          "name": "Jackson"
        },
        {
          "id": 203,
          "name": "Nkunku"
        },
        {
          "id": 204,
          "name": "Mudryk"
        },
        {
          "id": 205,
          "name": "Cucurella"
        },
        {
          "id": 206,
          "name": "Gusto"
        },
        {
          "id": 207,
          "name": "Caicedo"
        },
        {
          "id": 208,
          "name": "Fernandez"
        },
        {
          "id": 209,
          "name": "Gallagher"
        },
        {
          "id": 210,
          "name": "Silva"
        }
      ]
    }
  ],
  "selections": [
    {
      "marketId": 1,
      "outcome": "1"
    }
  ],
  "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,
            "103": 15,
            "104": 18.5,
            "105": 22,
            "106": 25.5,
            "107": 29,
            "108": 32.5,
            "109": 36,
            "110": 39.5,
            "201": 43,
            "202": 46.5,
            "203": 50,
            "204": 53.5,
            "205": 57,
            "206": 60.5,
            "207": 64,
            "208": 67.5,
            "209": 71,
            "210": 74.5
          },
          "*": {
            "101": 3.2,
            "102": 4.4,
            "103": 5.6,
            "104": 6.8,
            "105": 8,
            "106": 9.2,
            "107": 10.4,
            "108": 11.6,
            "109": 12.8,
            "110": 14,
            "201": 15.2,
            "202": 16.4,
            "203": 17.6,
            "204": 18.8,
            "205": 20,
            "206": 21.2,
            "207": 22.4,
            "208": 23.6,
            "209": 24.8,
            "210": 26
          },
          "-1": {
            "101": 8,
            "102": 11.5,
            "103": 15,
            "104": 18.5,
            "105": 22,
            "106": 25.5,
            "107": 29,
            "108": 32.5,
            "109": 36,
            "110": 39.5,
            "201": 43,
            "202": 46.5,
            "203": 50,
            "204": 53.5,
            "205": 57,
            "206": 60.5,
            "207": 64,
            "208": 67.5,
            "209": 71,
            "210": 74.5
          }
        }
      },
      "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
          }
        }
      }
    }
  }
}

Football 1 — Simple: Home WinFootball 2 — Simple: Away Win + Over 2.5 GoalsFootball 3 — Medium: Anytime Goalscorer + Home WinFootball 4 — Complex: Two Players to Score + Over 2.5 GoalsFootball 5 — Complex: Shots on Target + Player Assists + Away WinBasketball 1 — Simple: Home Win (NBA)Basketball 2 — Simple: Total Under 219 (NBA)Basketball 3 — Medium: Player Points Over 27.5 + Spread -5.5 (NBA)Basketball 4 — Complex: Player Points + Assists + Total Under (NBA)Basketball 5 — Complex: 4-Stat Parlay (Points + Rebounds + Steals + Blocks)American Football 1 — Simple: Home Spread -3 (NFL)American Football 2 — Simple: Total Over 49.5 (NFL)American Football 3 — Medium: Player Passing Yards Over 219.5 (NFL)American Football 4 — Complex: Player Anytime TD + Home Spread (NFL)American Football 5 — Complex: Passing Yards + Rushing Yards + TD + Moneyline (NFL)

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

Get supported markets for a sport

post

Returns the list of LSports markets supported by BetBuilder for a given sport, 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
}

All Football marketsSingle Basketball market

{
  "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"
        }
      ]
    }
  ]
}

Get supported leagues

post

Returns the leagues/tournaments supported by BetBuilder for a given sport, along with their format configuration (league mapping, available periods, whether extra time or playoffs are supported).

The leagueId in requests determines which league format is applied. Basketball and American Football require an explicit leagueId; Football accepts any.

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: 48242Possible values:

leagueIdinteger · nullableOptional

Optional filter — return data for a single league only.

Example: 64

Responses

200

List of supported leagues with format configuration

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/leagues

HTTPcURLJavaScriptPython

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

{
  "sportId": 48242
}

All Basketball leaguesNFL only

{
  "result": [
    {
      "sport": {
        "id": 48242,
        "name": "Basketball"
      },
      "league": {
        "id": 64,
        "name": "NBA"
      },
      "format": {
        "name": "NBA",
        "type": "basketball",
        "league": "NBA",
        "supportsExtraTime": true,
        "supportsPlayoff": true,
        "periods": [
          "*",
          "H1",
          "H2",
          "Q1",
          "Q2",
          "Q3",
          "Q4"
        ]
      }
    }
  ]
}