> For the complete documentation index, see [llms.txt](https://docs.hub88.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hub88.io/developer-docs/operator-api-reference/operator-api-overview.md).

# Operator API Overview

{% hint style="success" %}

#### ⚡ Hand this to your AI agent for Opertor API Integration

One prompt covering the five Wallet API endpoints you implement, every Operator API call, the request signing scheme, the `RS_*` statuses, and the idempotency rules. Paste it into your AI tool with your stack appended and it scaffolds a working integration.

{% file src="/files/QnPklec13S6oUAzcJLpT" %}

{% endhint %}

## Core APIs for Operator API

Operator API caters to all Operators whose goal is to integrate games into a third-party application through Hub88. For this, the following types of APIs are provided: 

* [**Games API**](/developer-docs/operator-api-reference/games-api.md) - allows Operators to request and receive the list of available games, which are provided and implemented by Hub88.
* [**Wallet API**](/developer-docs/operator-api-reference/wallet-api.md) - an API for Seamless wallets, which Hub88 triggers to update the user's balance. For this API, **the Operator needs to provide** corresponding endpoints based on the given API structures.
* [**Freebets API**](/developer-docs/operator-api-reference/freebets-api.md) - an API for granting rewards, such as free spins, free bets and prizes to one or multiple users. First-time user's bonuses are supported by most suppliers, however, in some cases a player must interact with the game before a free bet can be granted. 
* [**Recommendations API**](/developer-docs/operator-api-reference/recommendations-api.md) - Games' recommendation to an Operator based on player's interactions (game plays) on Hub88 platform. 
* [**Transactions API** ](/developer-docs/operator-api-reference/transactions-api.md)- an API which provides a list of all user's gameplay transactions.
* [**On-Demand API** ](/developer-docs/operator-api-reference/ondemand-api.md)- Specialized APIs available upon request. For accessing or setting up this functionality, please contact your technical contact on Hub88's side. 

***

## Operator SDKs

Operators looking to integrate with Hub88 have the option of utilizing two distinct Software Development Kits (SDKs). These SDKs provide the necessary tools and interfaces to seamlessly connect and manage various functionalities within the Hub88 platform. 

<table data-view="cards" data-full-width="false"><thead><tr><th align="center"></th></tr></thead><tbody><tr><td align="center"><a href="/developer-docs/operator-sdks/operator-games-api-sdk.md"><strong>Operator Games API SDK</strong></a></td></tr><tr><td align="center"><a href="/developer-docs/operator-sdks/thrilltech-jackpots-sdk.md"><strong>ThrillTech Jackpots SDK</strong></a></td></tr></tbody></table>

***

## Getting started

&#x20;To get started with setting up your integration with Hub88, you'll need to have the following:&#x20;

* **a public API key** provided by Hub88;
* **a private / public key pair** that you generate yourself;
* **an Operator ID** provided by Hub88;
* **a Game ID** provided by Hub88.

To receive a public key provided by Hub88, you'll need to contact <sales@hub88.io>. They'll trigger the process from technical integrations side, the process should be as follows:&#x20;

{% stepper %}
{% step %}
**Receive a public key sent from Hub88.**&#x20;
{% endstep %}

{% step %}
To generate **a private / public key pair** on **your side**, run the following commands:

* `openssl genrsa -out private.pem 2048`
* `openssl rsa -pubout -in private.pem -out public.pem`
  {% endstep %}

{% step %}
**Send the public key to Hub88.** Hub88 uses this public key to verify the **Games API** requests.&#x20;
{% endstep %}
{% endstepper %}

<figure><img src="https://1089485291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF8iFPgdqAwxIxP5oQMvU%2Fuploads%2FWZbWoqJAp2KEScFvQhBo%2FScreenshot%202025-09-18%20at%2015.24.00.png?alt=media&amp;token=c5f4d5a3-d03a-4280-b6a8-316f98f69f42" alt="" width="349"><figcaption></figcaption></figure>

### Request signing logic for Operator API&#x20;

The body of all requests will be signed with `RSA-SHA256` using the respective private key and encoded to BASE64.  The signature will be placed in the `X-Hub88-Signature` header.&#x20;

<figure><img src="https://1089485291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF8iFPgdqAwxIxP5oQMvU%2Fuploads%2F7tenQmxEFprdS3izhNSf%2F%5BHub88%5D%20Documentation%20working%20board%20(4).jpg?alt=media&amp;token=eca8e7e2-c236-49c9-81dd-9425c8d9c37d" alt=""><figcaption><p>Request signing for Operator API</p></figcaption></figure>

* **Games API**&#x20;
  * All **Games API** requests have to be signed by Operator.&#x20;
  * Hub88 verifies all **Games API** requests using the public key provided by the Operator.
* **Wallet API**
  * All **Wallet API** requests have to be signed by Hub88.&#x20;
  * The Operator needs to verify all **Wallet API** requests using the public key provided by Hub88.
* All **TransferWallet** API requests must be signed by the Operator.

We have [code examples](https://github.com/coingaming/Hub88-Examples/blob/master/README.md) in a few programming languages, to get you started.&#x20;

{% hint style="info" %}
**X-Hub88-Signature error:**

Ensure the X-Hub88-Signature has no whitespaces or beautifiers. The signature must match the body exactly—any difference will result in an "invalid signature" error.
{% endhint %}

**Example:**

<pre class="language-json" data-title="" data-overflow="wrap" data-line-numbers><code class="lang-json">{ 
    "user":"3nYTOSjdlF6UTz9Ir",
<strong>    "country":"XX",
</strong>    "currency":"EUR",
    "operator_id":1,
    "token":"cd6bd8560f3bb8f84325152101adeb45",
    "platform":"GPL_DESKTOP",
    "game_code":"clt_dragonrising",
    "lang":"en",
    "lobby_url":"https://examplecasino.io"
}
</code></pre>

* Private key example for signing the example request [here](https://raw.githubusercontent.com/coingaming/Hub88-Examples/master/priv/private.pem).

{% code title="Signature example:" overflow="wrap" %}

```
DYKK0KsSMayoyHcpFx32R57mZ8ey2r8U4RscT9LiWEFkd40V/f2n9JafsC+yuB8OSHz+wdCvyxvqacNiL8r3ZGEBdTL4lrcjdM5PWHQu8auYNp2mGE0tbX6/KGyk8nyQ3+h1HogIHj5hnMNYx0r+AhFT2tD/IT2b3Pq6oDPNL8rK0CbDCm8w7+gal1i0T1pDo61e2CTDTHpfm4ELEKcff2iiIRvgQ52nUCkuxQjCN/BGyEC1il0AVwlcb8CKU6Utg48UqvPLqu38qahI5X53zBMpLFIOtOYcFoepWmHvBxh0GDM4NIfQQ3Cm5sFyN3AsqzM7rqA0N9VZP0QPK8fA0g==
```

{% endcode %}

### Request consistency&#x20;

**Wallet API** requests have to be idempotent. All transactions contain a `transaction_uuid` field. The Operator has to ensure that requests with the same `transaction_uuid` are not processed twice, while the response has to be the same for all duplicate requests. The operator may ignore the idempotency requirement for the `/user/balance` call.

## API evolution and forward compatibility

Hub88 extends the Operator API over time to support new features. Most of these changes are additive and are released without a new API version. Your integration must be built to accept them.

#### What Hub88 considers non-breaking

The following changes can be released at any time without a version change:

* New optional fields in requests Hub88 sends to you (for example, Wallet API calls to your endpoints)
* New optional fields in responses Hub88 returns to you (for example, Games API, Freebets API and Transactions API responses)
* New values in existing enum-like fields
* New endpoints

Breaking changes are announced separately, with a migration path and a deadline. Examples include removing or renaming a field, changing a field's type, or making an optional field required.

#### What your integration must do

* **Ignore unknown fields.** Don't reject a request or response because it contains a field you don't recognise.
* **Tolerate new enum values.**
* **Verify signatures on the raw body.** Verify `X-Hub88-Signature` against the exact bytes received, before deserialising. Re-serialising a parsed object drops unknown fields, which changes the body and breaks verification. See[ Request signing logic for Operator API](#request-signing-logic-for-operator-api).

{% hint style="warning" %}
The Wallet API compatibility is the most crucial. Hub88 calls your endpoints, so a wallet that rejects an unknown field will cause bets, wins and rollbacks to fail in production.&#x20;
{% endhint %}

#### How changes are announced

All Operator API changes are published in the [API Changelog](https://docs.hub88.io/api-changelog/). Non-breaking additions are announced at the time of production release. Breaking changes are announced with a migration guide and a deadline for action.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hub88.io/developer-docs/operator-api-reference/operator-api-overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.