Oddin.gg Trading Service documentation

1. General information

1.1. OTS API

Our API is based on gRPC and protocol buffers. The gRPC-based communication is 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
• Oddin.gg OTS protocol buffer message schemas: https://github.com/oddin-gg/otsschema

1.2. Environments

We currently provide two different environments - Production and Integration. The Production environment is intended to be used only when you have finished with the integration and are ready to go live. Please use the Integration environment for all testing and integration purposes.

You can find the endpoint for each environment in the following table:

1.3. gRPC concepts

You can find the service description and message scheme on https://github.com/oddin-gg/otsschema. You can generate binding codes from this message scheme for your desired language, or you can use pre-generated bindings for Java, Go, and Node.js:

• A typical request to gRPC is a unary request. You will send us a request, and we will deliver a response in one rpc call.
• For tickets, we are using gRPC bidirectional streaming, where you need to send keepalive messages if you want to have an open stream for a long time.

ℹ You should not create one stream for each ticket, but rather keep only one stream open and send multiple tickets as needed.

1.4. Authentication

Access to the API is only allowed from known IP addresses. Please send us your IP range(s) to us through your dedicated Oddin.gg communication channels and we will whitelist you.

You have to use an access token to access the OTS API. You should be able to obtain this access token for each environment in Oddin.gg Settings Platform (back-office). Typically, access tokens are valid for one year and are extended automatically.

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

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

Example of a token setting (Go)

1.5. Integration environment

Please use the integration environment to test your connection and message format. It automatically accepts bets, but every fifth bet is rejected. You can cancel bets at will.

1.6. Handicap markets

Handicap markets can be communicated differently in various Oddin.gg betting products:

• Vanilla: default handicap sign
• Inverted: inverted handicap sign (used by most booking operators)

Example - Team handicap +/-1.5:

2. Exchange rates

We use euro (EUR) as our system currency. All non-EUR currencies are converted by exchange rates from OpenExchange: https://openexchangerates.org - all valid ISO 4217 currency codes should be accepted: https://en.wikipedia.org/wiki/ISO_4217. Exchange rates are updated every 30 minutes.

Ticket currency conversion process:

• Exchange rates are rounded to 6 digits after the comma
• The tickets are converted using the exchange rate based on the ticket timestamp
• The winning values are calculated based on the converted EUR value

3. Bettor bonuses

Please include information about the betting bonuses (the bettor receiving a percentage uplift on the winnings base by some criteria) present in the ticket for the given bettor. We use it as additional information to monitor bettors and its potential abuse of betting bonuses. It does not affect bettor liability and risk score.

If such a bonus is offered, the bonus winning amount must be included in the appropriate BetBonus (see the chapter BetBonus fields) object for each bet.

4. Odds auto acceptance

We offer the option to automatically accept tickets if odds move outside the acceptable limit. You can set this field in the ticket request to ANY or HIGHER enum.

• ANY - all odds changes will be accepted
• HIGHER - only higher odds will be accepted

5. Ticket reoffer

We offer the option to “reoffer” a ticket again with a different stake. This will significantly reduce bettors' rejection rates and improve their experience. Please check the following bet reoffer flow:

1. The ticket is sent to the OTS
2. The ticket is rejected because of limited liability
3. The rejected ticket contains the reoffer stake in the local currency of the bet
4. A new ticket is placed with the reoffer_id set to the previously rejected ticket

6. Ticket processing flow

This chapter provides a complete reference on how tickets are handled by OTS. It is very important to follow the flow described here; otherwise, the OTS cannot guarantee the ticket processing. Please check the diagram at the end of this chapter for a more detailed description.

6.1. Ticket process flowchart

6.2. Acceptance process

• The Client sends a ticket to the OTS.
• The system sends back a Ticket Response with an acceptance status of Accepted or Rejected
  • If a response is not received within bet delay + 5 seconds (default betting delay is 0 seconds for prematch and 5 seconds for live), the bet should be rejected, and the ticket cancellation message sent to the OTS (please check Ticket Cancellation). These times are configurable and can be changed based on tournament/bettor specific settings. Maximum delay is 120 seconds.

• If the ticket was Accepted by the OTS, we expect the ticket to be accepted by the client’s system as well. If you need to reject the ticket, please follow this:
  • Send the ticket cancellation to the OTS (please check the chapter Ticket Cancellation)
  • If the ticket cancellation was Accepted
    • Client rejects the bet
    • The ticket acknowledgment request with the Rejected status is sent to OTS
  • If the ticket cancellation was Rejected
    • The Client should accept the bet, however if you still need to cancel it, please contact us at support@oddin.gg or your integration channel

• If the ticket was Rejected by OTS, we expect the ticket to be rejected by the client’s system as well. If you need to accept the rejected ticket, then send the ticket acknowledgment request with Accepted status.

6.3. Ticket cancellation

It is sometimes necessary to cancel a bet. Bet cancellation can have various reasons, but the OTS system needs to know about all cancellations on the client’s side in order to properly manage the liability. We support specific bet cancel scenarios (please check the next table), which need to be correctly set in the TicketCancelRequest message. A ticket can be cancelled only up to 5 minutes after it has been accepted.

CancelReason descriptions

The ticket cancellation can be Accepted or Rejected by the OTS system. Please check the possible rejection codes for the ticket cancellation:

CancelRejectionReason descriptions

6.4. Ticket acknowledgment

By default, clients should follow the ticket Accepted or Rejected status, otherwise we cannot guarantee liability processing. In case you do not follow our recommendation, you have to always cancel the ticket and send a ticket acknowledgment message with the final ticket state. We expect to receive the ticket acknowledgment within 10s after you receive the initial ticket response.

7. Message schemas

This chapter offers an in-depth description of each field of the message schemas. Please check https://github.com/oddin-gg/otsschema for the protocol buffer definition of the messages.

7.1. Ticket request schema

7.1.1. TicketRequest fields

We are using gRPC bidirectional streaming for tickets, where you need to send keepalive messages if you want to have an open stream for a long time. Keepalive messages must be sent every 10 seconds.

*One of the parameters must be present TicketRequest fields

7.1.1.1. Ticket fields

*In the case of foreign (non-Oddin) event odds selections on the ticket, one of the fields needs to be present.
Ticket fields

7.1.1.1.1. Bet fields

Bet fields

7.1.1.1.1.1. BetBonus fields

BetBonus fields

7.1.1.1.1.2. BetStake fields

BetStake fields

7.1.1.1.1.3. Bet types for the systems field

Bet type descriptions

7.1.1.1.1.4. BetSelection fields

BetSelection fields

7.1.1.1.2. TicketCustomer fields

TicketCustomer fields

7.1.1.1.3. TicketSelection fields

TicketSelection fields

7.1.1.1.3.1. Selection ID

Please use the selection information you get from the odds feed in this format:

"<event_urn>/<market_id>/<outcome_id>?<specifier1>=<value1>[&<specifierN=valueN>]*"

• event_urn - event urn from feed REST API
• market_id - market ID from feed REST API
• outcome_id - outcome ID from feed REST API
• specifier and value - specific specifiers for every market from feed AMQP messages

example:

"od:match:1234/6/1?map=1&way=two"

7.1.1.1.3.2. OBBSessionInfo fields

7.1.1.2. StreamKeepalive fields

StreamKeepalive fields

7.1.1.3 TicketCashout fields

TicketCashout fields

7.1.1.3.1 BetCashout fields (NOT to be used!)

BetCashout fields (NOT to be used!)

7.1.1.4. TicketMaxStake fields

TicketMaxStake fields

7.2. Ticket response schema

7.2.1. TicketResponse fields

*One of the parameters must be present TicketResponse fields

7.2.1.1. TicketState fields

TicketState fields

ℹ We recommend not to set a fixed time limit for voiding tickets without a response. The preferred method is to take the delay information (seconds) from the pending_delay field and add 5 seconds to it - if after this combined time there is no response from the OTS system, the ticket should be voided.

7.2.1.1.1. TicketRejectReason fields

TicketRejectReason fields

7.2.1.1.1.1. TicketRejectReason codes

TicketRejectReason code descriptions

7.2.1.1.2. TicketResponseBetInfo fields

TicketResponseBetInfo fields

7.2.1.1.2.1. TicketBetRejectReason fields

TicketSelectionRejectReason fields

7.2.1.1.2.1.1. TicketBetRejectReason codes

TicketBetRejectReason codes

7.2.1.1.3. TicketSelectionRejectReason fields

TicketSelectionRejectReason fields

7.2.1.1.3.1. TicketSelectionRejectReason codes

TicketSelectionRejectReason code descriptions

7.2.1.1.4. AutoAcceptedOdds fields

AutoAcceptedOdds fields

7.2.1.2. TicketCashoutState fields

TicketCashoutState fields

7.2.1.2.1. TicketCashoutRejectReason fields

TicketCashoutRejectReason fields

7.2.1.2.1.1. TicketCashoutRejectReason codes

TicketCashoutRejectReason code descriptions

7.2.1.3. TicketMaxStakeState fields

TicketMaxStakeState fields

7.3. Ticket result request schema

7.3.1. TicketResult request

*One of the parameters must be present TicketResultRequest fields

7.3.1.1 TicketResult fields

TicketResult fields

7.3.1.2. TicketsAfter fields

TicketsAfter fields

7.4. Ticket result response schema

7.4.1. TicketResult response

*Based on the request, one will be sent TicketResultResponse fields

7.4.1.1. TicketResultState fields

TicketResultState fields

7.4.1.1.1. TicketResultStateBetInfo fields

TicketResultStateBetInfo fields

7.4.1.1.2. TicketResultStateSelectionInfo fields

TicketResultStateSelectionInfo fields

7.4.1.1.3. TicketResultError fields

TicketResultError fields

7.4.1.2. TicketAfterState fields

TicketResultState fields

7.4.1.2.1. BatchInfo fields

BatchInfo fields

7.4.2. TicketResult flow (cross bets and combo bets)

7.5. Ticket acknowledgement schema

TicketAckRequest fields

7.6. Ticket cancel schema

7.6.1. TicketCancelRequest fields

TicketCancelRequest fields

7.6.1.1. CancelBetInfo fields (currently not supported!)

CancelBetInfo fields

7.6.2. TicketCancelResponse fields

TicketCancelResponse fields

7.7. Player risk score schema

You can use this method to get more insight on individual player risk score.

7.7.1. PlayerRiskScore request

PlayerRiskScoreRequest fields

7.7.2. PlayerRiskScore response

PlayerRiskScoreResponse fields

7.8. Resolve foreign events schema

7.8.1. ResolveForeignEventsInTicket request

ResolveForeignEventsInTicketRequest fields

7.8.2. ResolveForeignEventsInTicket response

ResolveForeignEventsInTicketResponse fields

7.9. Health schema

7.9.1. HealthCheck request

HealthCheckRequest fields

7.9.2. HealthCheck response

HealthCheckResponse fields

7.9.2.1. ServingStatus codes

ServingStatus code descriptions

More details about the implemented gRPC Health Checking Protocol at: https://github.com/grpc/grpc/blob/master/doc/health-checking.md

8. Risk API

8.1. Introduction

Oddin.gg Risk API service API is an extension of the OTS service, offering enhanced functionalities for sending tickets and managing bettor properties. It provides you with robust tools to manage bettor liabilities, leverage valuable customer information, and automate critical processes.

Key Features:

• Comprehensive Metadata Integration: Each bettor is associated with betting score labels and metadata, which are essential for calculating maximum liabilities and managing risks effectively.
• Utilise Existing Customer Information: Make the most of your valuable bettor data to optimise your risk management strategies.
• Streamlined Data Sharing: With API access, you can automate the process of sharing bettor information, eliminating the need for manual processing through trading chats. This ensures faster and more accurate adjustments to risk management settings.
• Automated Bettor Management: Easily import lists of bettors, and set limitations even before they place their first bet. The API allows bulk adjustments, saving time and reducing manual errors.
• Real-time Adjustments and Monitoring: The system includes a push feed for each client, ensuring that adjustments to the risk management settings are communicated in a timely fashion. This allows for real-time monitoring and review of the risk management processes.

The Risk API is designed to be flexible and scalable, capable of supporting a wide range of services and automating bettor labelling processes throughout the year.

8.2. Concepts

The Risk API gRPC schema is available on Oddin.gg GitHub repository: https://github.com/oddin-gg/otsschema/pull/10/files. 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.

• Extended OTS gRPC API with one unary gRPC stream which pushes updates about Bettor’s risk coefficients to the clients. The stream supports recovery since a given timestamp (max. timestamp threshold is configurable).
• As Bettor’s risk coefficients we consider bettor information such as: BOS (Bettor’s Oddin Score), OAF (Over Ask Factor), Oddin.gg labels, and Client labels.
• The API supports authorisation and authentication.

8.3. Endpoints

8.3.1. BettorsRequest

BettorsRequest field

8.3.2. BettorsResponse

BettorsResponse fields

8.3.2.1. Bettor

Bettor fields

8.3.2.2. StreamKeepAlive

StreamKeepAlive field

8.3.3. BettorUpsertRequest

This request is used to update or create a bettor.

BettorUpsertRequest fields

ℹ When sending bos and over_ask_factor, only one of these parameters can have their value other than 1.

8.3.4. BettorUpsertResponse

This message contains the updated bettor information.

BettorUpsertResponse field

8.3.5. AvailableBettorLabelsRequest

This message is used to request the list of available bettor labels.

8.3.6. AvailableBettorLabelsResponse

This message contains the list of available bettor labels.

AvailableBettorLabelsResponse field

8.4. Logic and workflow

8.4.1. Implement gRPC client

• Objective: Implement a gRPC client for the Bettor stream.

8.4.2. Initial connection

• Send initial request: When the client connects for the first time, it must send a request with the timestamp set to a minimum value (e.g., 28/11/2018).
  • Purpose: To trigger a full recovery and receive all available Bettors.

• Send latest timestamp: For subsequent connections, the client sends the latest timestamp it has received and stored.
  • Purpose: To receive only updates that occurred after the last recorded update, ensuring no data is missed.

• No recovery mode: If the client sends a request with a null value for the timestamp, it will receive only new updates.
  • Risk: The client may miss updates that occurred while it was disconnected.

8.4.3. Continuous updates and database management

• Update storage: Upon receiving Bettor updates via the gRPC stream, the client must:
  • Load: Load Bettor for the given id/ext_id from the database.
  • Store: Store received Bettors in the case when no such bettor is stored in DB.
  • Conditionally update: In case when Bettor is already stored in the DB. You are supposed to compare timestamps; if the incoming update’s timestamp is higher or equal to the stored one, update the record in the DB. Ignore the received update if the update has the modified_at timestamp lower than the already stored timestamp for the same id/ext_id.

8.4.4. Keepalive messages

• Connection maintenance:
  • The OTS service will send keepalive messages every 10 seconds to ensure the connection remains active. If you do not receive a keepalive message within 20 seconds, please restart the connection.

8.5. Risk API integration examples

8.5.1. AvailableBettorLabels

Retrieves a list of all available labels that can be assigned to a bettor.

grpcurl example:

grpcurl --plaintext \
  -H "token: XXXXX-XXXXX-XXXXX-XXX-XXXXX" \
  api-ots.integration.oddin.gg \
  ots.ots/AvailableBettorLabels

8.5.2. BettorUpsert

Creates a new bettor or updates an existing one based on the provided id.

• Create: If the id does not exist, a new bettor is created.
• Update: If the id exists, this endpoint performs a partial update. Only the fields provided in the request payload will be modified. Any omitted fields will retain their current values.

grpcurl example:

grpcurl --plaintext \
  -H "token: XXXXX-XXXXX-XXXXX-XXX-XXXXX" \
  -d @ \
  api-ots.integration.oddin.gg \
  ots.ots/BettorUpsert < data.json

Request payload parameters:

• id (string, required): The unique identifier for the bettor.
• bos (number, optional)
• over_ask_factor (number, optional)
• labels (object, optional): An object containing a values array of strings to set or overwrite the bettor's labels.
• nickname (string, optional)

Here are several examples of data.json payloads for different scenarios:

8.5.2.1. Create or full update

Action: Sets all specified parameters for the bettor.

{
        "id": "3257ff3b-b26e-40eb-9ee6-88d3f82f5701",
        "bos": 1,
        "over_ask_factor": 7.001,
        "labels": {
                "values": ["VIP"]
        },
        "nickname": "nickname1"
}

8.5.2.2. Partial update (BOS only)

Action: Updates only the bos value. All other parameters (over_ask_factor, labels, nickname) are unaffected.

{
        "id": "3257ff3b-b26e-40eb-9ee6-88d3f82f5701",
        "bos": 0.5
}

8.5.2.3. Remove assigned labels

Action: Removes all labels from the bettor by passing an empty values array.

{
        "id": "3257ff3b-b26e-40eb-9ee6-88d3f82f5701",
        "labels": {
                "values": []
        }
}

8.5.2.4. Update nickname

Action: Updates only the nickname.

{
        "id": "3257ff3b-b26e-40eb-9ee6-88d3f82f5701",
        "nickname": "nickname2"
}

8.5.2.5. Update constraints

Action: Updates both bos and over_ask_factor simultaneously.

{
        "id": "3257ff3b-b26e-40eb-9ee6-88d3f82f5701",
        "bos": 1,
        "over_ask_factor": 9.95
}