External betslip

By default the betting frame ships its own betslip: it collects the odds the player clicks, shows the stake form and places the bet. A platform that already has a betslip of its own can keep it and use the frame only for browsing events, markets and odds. The frame then reports every odd click to your platform and highlights the odds your betslip holds. Everything else, from the betslip rules to bet placement, stays in your platform and does not go through the frame.

The contract has two events:

Both events identify an odd by the same triple, and both carry Bet Builder legs in a separate betBuilderSelections array (see Bet Builder):

1
2
3
4
5

interface BettingSelection {
  sportEventId: string;
  marketId: string;
  oddId: string;
}

Prerequisites

• Betting frame initialized through any of the integration modes that expose bettingAPI. The betting-betslip container is not needed in this setup.

How it works

1. The player clicks an odd in the frame. The frame emits odd-click with the clicked selections. It does not store them and does not decide what the click means.
2. Your betslip applies its own rules: add the selection, remove it if it is already there, replace another selection of the same event, reject it, and so on.
3. After every change your platform sends the whole betslip back with betslip-selections-change.
4. The frame highlights the odds listed in the last snapshot. The snapshot is kept, so odds rendered later (navigation, expanded markets, tabs) are highlighted as well without another call.

The frame never guesses the state of your betslip: an odd is highlighted only because your last snapshot lists it. A click alone highlights nothing until your snapshot arrives.

Full example

myBetslip stands for your own betslip; its methods are placeholders.

 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

// Your betslip item → the frame's selection triple.
const toSelection = ({ eventId, marketId, outcomeId }) => ({
  sportEventId: eventId,
  marketId,
  oddId: outcomeId,
});

function connectBetslip(bettingAPI) {
  // The frame reports a click; your betslip decides what it means.
  // A bundle can fill both arrays: apply them as one change.
  const offClick = bettingAPI.subscribe("odd-click", ({ selections, betBuilderSelections }) => {
    myBetslip.applyClick({ selections, betBuilderSelections });
  });

  // The frame highlights only what the last snapshot lists:
  // send it on start and after every change, including the ones caused by a click.
  const publish = () =>
    bettingAPI.emit("betslip-selections-change", {
      selections: myBetslip.items().map(toSelection),
      betBuilderSelections: myBetslip.betBuilderLegs().map(toSelection),
    });
  publish();
  const offChange = myBetslip.onChange(publish);

  return () => {
    offClick();
    offChange();
  };
}

Call connectBetslip(bettingAPI) once bettingAPI is available — in the onLoad callback for the SPA integration or on betting-init for the SSR integration — and call the returned function when your page removes the frame. The steps below explain each part.

Step 1. Listen to odd clicks

Subscribe to odd-click once bettingAPI is available. A plain click carries one selection. A bundle, for example a pre-generated bet card, carries several selections that belong together, and can fill selections and betBuilderSelections in the same click. Apply both arrays to your betslip as one change, so a single snapshot goes out and the frame never sees half of the bundle.

The payload carries identifiers only. Use them to request the current odd value, market name and event details from your platform; the value shown in the frame at the moment of the click may already be outdated.

For reference, the built-in betslip toggles a single selection (adds it, or removes it when it is already in the betslip) and adds the missing members of a bundle while keeping the ones already selected. Your betslip is free to apply different rules.

Bet Builder

A Bet Builder is a single bet consisting of multiple selections (legs) from the same event. The frame reports the legs in betBuilderSelections and never mixes them into selections: a click in a Bet Builder market reports one leg, a pre-generated Bet Builder card reports all of its legs, and a bundle that combines regular odds with a Bet Builder reports both arrays. Group the legs by sportEventId: each group is one Bet Builder your betslip prices and places. Report them back in the betBuilderSelections array of the snapshot, and the frame highlights them in the Bet Builder markets. The total odds of a Bet Builder are calculated on your side.

Step 2. Report your selections

Send the full betslip with betslip-selections-change whenever it changes. It is a snapshot, not a delta: the frame replaces its previous state with the arrays you send.

Call it:

• on start, once bettingAPI is available: in the onLoad callback for the SPA integration, or on betting-init for the SSR integration;
• after every change of your betslip: add, remove, replace, clear, a placed bet, including the changes triggered by odd-click.

Map your betslip items to the selection triple, as toSelection does in the full example. An empty array removes every highlight; betBuilderSelections can be omitted when your betslip has no Bet Builders. Extra fields in a selection are ignored; a payload without a selections array is logged as an error and ignored.

Step 3. Place the bet

The stake form, validation and placement are yours and happen outside the frame. Once the bet is placed, clear your betslip and publish the empty snapshot so the frame drops the highlights.

Because the frame is not involved in placement, the events it emits around its own bet flow (handle-not-enough-balance, handle-custom-errors, toggle-widget-betslip) do not fire in this setup. Handle those cases in your own betslip UI.

Checklist

• odd-click is handled by your betslip's own rules; the frame does not apply any. Bet Builder legs come in their own betBuilderSelections array, possibly in the same click as regular selections; both are applied as one change.
• betslip-selections-change is sent on start, once bettingAPI is available, and after every change, including a clear and a placed bet.
• Odds that appear after navigation are highlighted without an extra call.
• Subscriptions are removed when your page removes the frame.
• Bet placement happens in your platform, outside the frame.