Oddin.gg BetBuilder (OBB) documentation

Introduction

Oddin.gg BetBuilder (OBB) allows bettors to create a combo (multiple-selection) bet using selections from the same match. This is typically not possible due to the correlation of probabilities between the markets in the same match. Unlike a standard combo bet, the odds for BetBuilder cannot be calculated simply by multiplying the selected market odds. Instead, a complex model is needed to compute the final ticket odds.

The goal of every booking operator is to expand the betting offer and provide a unique and engaging way for the punters to interact with the odds. Oddin.gg BetBuilder (OBB) enables punters to become more invested in Esports matches and bet on specific outcome combinations within the same match.

1. General information

In this chapter, you will find general information regarding fundamental concepts and processes of the OBB service. If you have further questions, or you feel that our documentation does not provide the required information, please contact us through your dedicated Oddin.gg communication channels.

1.1. Supported Esports and eSimulators

Oddin.gg BetBuilder (OBB) is currently available for the following Esports and eSimulators:

• Counter-Strike 2 (CS2) – Prematch-only
• Counter-Strike 2 Duels (CS2 Duels) – Prematch-only
• Valorant – Prematch-only
• eFootball & eFootball bots – Prematch and Live
• eBasketball – Prematch-only

1.2. Concepts

Oddin.gg BetBuilder (OBB) is a natural extension of our existing services and offering. It is an extended functionality for betting markets, where we would consider a combination of OBB market selections as one selection inside a combo or single ticket.

1.3. Session

The core concept of bet placement with OBB is a session. A session identifies one unique combination of selections (betting opportunities). Each new combination of selections creates a new session. This process can be repeated multiple times with different selection combinations.

1.4. Markets

A betting market is a combination of multiple selections. OBB uses the same identifiers for markets and selections as are available in the Odds Feed Service. The list of OBB-supported markets per sport is available in the Oddin.gg Markets and Sports document.

1.5. Environments

1.6. Authentication

Access to the API is only allowed from known IP addresses. Please send us your IP range(s), and we will whitelist you.

You have to use an access token to access the OBB API. You should obtain this access token through the Oddin.gg Settings Platform (back-office). To get access to the Settings Platform, please contact us through your Oddin.gg communication channels. Typically, access tokens are valid for one year and should be extended automatically.

The access token has to be inserted into the gRPC context with the “token” key.

grpc.Dial(target,
   grpc.WithPerRPCCredentials(&grpcToken{
      token: "xxxxxx",
   }))

Example of a token setting (Go)

1.7. Rate limiting

We limit the Session endpoints to protect the API. Please check the table below for more granular rate limits:

2. OBB API

The Oddin.gg BetBuilder (OBB) API is based on gRPC and protocol buffers. gRPC-based communication has been battle-proven by software industry giants like Google, Microsoft, and others. It offers simple export and client/server code generation for many languages (Java, C#, Python, Node.js, Go, and others). We use protocol buffers as a message format. It is an extremely lightweight and data-saving format, used in many applications.

• More about gRPC: https://grpc.io
• More about protocol buffers: https://developers.google.com/protocol-buffers
• OBB protocol buffer message schema: https://github.com/oddin-gg/obbschema

2.1. gRPC concept

The OBB gRPC schema is available on the Oddin.gg GitHub: https://github.com/oddin-gg/obbschema.
You can generate binding codes from this message schema for your desired development language. A typical request to gRPC is a unary request. You send us a request, and we deliver a response in one RPC call.

2.2. Available endpoints

2.3. AvailableMarkets endpoint

2.3.1. AvailableMarkets request

2.3.2. AvailableMarkets response

2.3.2.1. AvailableMarket

2.4. SessionCreate endpoint

2.4.1. SessionCreateRequest

2.4.2. SessionCreateResponse

2.4.2.1. Status

2.4.2.1.1. SessionCreated

2.4.2.1.1.1. SessionMarket

2.4.2.1.1.1.1. SessionMarketOutcome

2.4.2.1.2. SessionRejected

2.4.2.1.2.1. SessionRejectReason

2.4.2.1.2.1.1. SessionRejectReason codes

2.5. SessionInfo endpoint

2.5.1. SessionInfoRequest

2.5.1.1. SessionSelection

2.5.2. SessionInfoResponse

2.5.2.1. Status

2.5.2.1.1. ValidSession

If the parameter exists, the session is valid.

2.5.2.1.2. InvalidSession

2.5.2.1.2.1. InvalidSessionReason

2.5.2.1.2.1.1. InvalidSessionReason codes

2.6. PopularCombination endpoint

Returns ready-made, priced selection combinations (“quick picks”) for a match. Each combination’s selection_ids use the exact SessionCreateRequest.selection_ids format, so you can echo them verbatim into SessionCreate for one-click placement – no per-selection assembly is needed.

Combinations are built only from markets you actually receive in your Odds Feed and only from markets that combine validly with each other (no cross-map-part combinations, no repeated market types, and winner and handicap markets are never combined). Each offered combination is re-priced through the same correlation-aware simulation path as SessionCreate, so it is creatable at the quoted odds at offer time. The offered odds are indicative: SessionCreate re-prices when the bettor clicks, and the odds can change or the combination can be rejected. The bet must always be placed on the SessionCreate odds.

2.6.1. PopularCombinationRequest

2.6.2. PopularCombination response

2.6.2.1. PopularCombination

ℹ An empty response is normal, not an error. It simply means there is nothing to offer for that match right now – for example, the event has no OBB support or no combinable markets. You should show nothing rather than surface an error.

2.7. Caching

We are caching almost all API endpoints to optimise performance. The cache is not invalidated by entity changes. We always wait for the entity TTL expiration. Please check the table below for the TTL information:

ℹ The AvailableMarkets response is not cached with a fixed TTL. It is computed per request from the live odds feed and the per-event BetBuilder availability, both updated in near-real time. Re-polling the endpoint reflects availability changes within seconds. Internal metadata caches (event/client attributes) may delay some changes by minutes up to ~1 hour and refresh on TTL expiry.

3. Workflow

3.1. Concepts

• Website opening:
  • A client should call AvailableMarkets to get a list of available BetBuilder markets for the event.
  • A client can also call PopularCombination when the match page opens to obtain ready-made, priced selection combinations. When a bettor picks a combination, its selections are passed straight into SessionCreate: the returned selection_ids are already in the SessionCreateRequest format, so no transformation is needed on the client side.

• Session:
  • The term used to describe the process of creating a bet in BetBuilder.
  • Bettors/punters typically select one selection and expect new odds.
  • This process can be repeated multiple times with different selection combinations.
  • Each new combination creates a new session.

• Ticket risk management (for OTS clients):
  • Clients gather selection_id(s), odds, and the session_id for each BetBuilder ticket.
  • Upon the bet placement, a new ticket request is sent to OTS by the client.
  • OTS validates the ticket against OBB (through session_id).
  • The ticket is accepted or rejected.

• Odds invalidation:
  • All sessions which contain changed selection(s) are invalidated and sent to clients.
  • SessionInfo should be polled periodically, as it returns the information about the session validity.
  • Clients must create a new session by requesting SessionCreate.

3.2. BetBuilder mode switching

A front-end solution to display the odds in the BetBuilder mode can have either the following:

1. A manual switch to the BetBuilder mode by punters via a button, OR
2. An automatic switch when a punter starts adding selections to the bet slip, for example:
   1. A bettor adds a Map winner selection to the bet slip.
   2. They try to add other selections from the same map (period) to the bet slip.
   3. A modal appears, informing the bettor about the BetBuilder functionality, allowing them to switch to the BetBuilder mode or remove the previous selection:
      • removes the old selection and adds a new one → continues with normal single/combo flow, OR
      • accepts and switches to the BetBuilder mode.

3.3. Betting flow examples

3.3.1. Example #1: Placing an OBB bet & risk management through OTS

1. Client (FE) → Client platform (BE): Bettor adds Selection X to the bet slip.
2. Client platform (BE) → OBB service (BE): A new SessionCreate request is sent, including Selection X.
3. OBB service (BE) → Client platform (BE): A response with a session_id, SessionMarket array, SessionSelection array, and optional RejectionReason is received.
4. Client platform (BE & FE): The response message is accepted, and on the FE appropriate selections are disabled OR their odds are updated based on the SessionMarketOutcome.
   • → Steps 1. – 4. can be repeated as long as there are any available selections left.

1. Client platform (BE) → OTS service (BE): The BetBuilder ticket (the betting ticket constructed with the BetBuilder selection_id) is sent through the OTS service, the same as a regular ticket, but it also includes the OBB session_id.
2. OTS service (BE) → Client platform (BE): The response is sent back through the OTS service with either a) rejection and reoffer OR b) information about the ticket being accepted.
   • If the ticket is rejected, the bettor can adjust the stake and resend the ticket → Step 5.

1. Client platform (BE): The ticket is saved in the system with the accepted status.
2. The match ends and all markets are resolved on the Oddin.gg side.
3. OTS service (BE) → Client platform (BE): Ticket status is updated and sent through OTS.

3.3.2. Example #2: Odds change during the OBB bet-building process

1. Client (FE) → Client platform (BE): Bettor adds Selection X to the bet slip.
2. Client platform (BE) → OBB service (BE): A new SessionCreate request is sent, including Selection X.
3. OBB service (BE) → Client platform (BE): A response with a session_id, SessionMarket array, SessionSelection array, and optional RejectionReason is received.
4. Client platform (BE & FE): The response message is accepted, and a) on the FE appropriate selections are disabled OR b) their odds are updated based on the SessionMarketOutcome.
5. Odds Feed (BE) → OBB service (BE): Change of odds is received from the odds feed.
6. Client platform (BE) → OBB service (BE): A SessionInfo request is made to the OBB API.
7. OBB service (BE) → Client platform (BE): SESSION_STATUS_INVALID is received in SessionStatus.
8. Client platform (BE) → OBB service (BE): A new SessionCreate request is sent, including Selection X.
9. OBB service (BE) → Client platform (BE): A response with a session_id, SessionMarket array, SessionSelection array, and optional RejectionReason is received with new, up-to-date odds.
10. Back to → Step 4. under Example #1, and the process continues.

3.3.3. Example #3: PopularCombination one-click placement & risk management through OTS

1. Client (FE) → Client platform (BE): The bettor opens the match page.
2. Client platform (BE) → OBB service (BE): AvailableMarkets is called to load the available BetBuilder markets for the event.
3. Client platform (BE) → OBB service (BE): PopularCombination is called for the same event.
4. OBB service (BE) → Client platform (BE): A response with a list of ready-made, priced combinations is received. An empty list is normal – the client simply shows nothing.
5. Client (FE): The bettor picks one of the offered combinations.
6. Client platform (BE) → OBB service (BE): A SessionCreate request is sent, echoing the offered selection_ids verbatim (no transformation on the client side).
7. OBB service (BE) → Client platform (BE): A response with a session_id, SessionMarket array, SessionSelection array, and final odds (or a RejectionReason) is received. The bet is placed on these SessionCreate odds, which may differ from the indicative PopularCombination odds.
8. Client platform (BE) → OTS service (BE): The BetBuilder ticket is sent through OTS for risk management, as in Example #1.
9. OTS service (BE) → Client platform (BE): The ticket is accepted or rejected (with reoffer), and the final ticket status is returned through OTS.