> 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/api-changelog/october-2026/operator-api-your-integration-must-ensure-forward-compatibility.md).

# Operator API: your integration must ensure forward compatibility

Announced: October 1, 2026

**Action required by: 15 October 2026**

***

We regularly extend the Operator API with new optional fields to support new features. These are additive, non-breaking changes. \
\
However, integrations that validate our payloads strictly and reject any unknown field can fail when a new field appears. This notice sets out what we expect from every Operator integration, and what to change if your implementation validates strictly today.

{% hint style="info" %}
**This applies to the Operator Generic API:** \
Wallet API, Games API, Freebets API, Transactions API and all other Operator API surfaces.
{% endhint %}

## **What's changing?**

As part of normal API evolution, Hub88 may add new optional fields to:

* **Requests Hub88 sends to you.** This includes Wallet API calls to your endpoints, such as `/transaction/bet`, `/transaction/win`, `/transaction/rollback` and `/user/balance`.
* **Responses Hub88 returns to you.** This includes Games API, Freebets API and Transactions API responses.

We may also add new values to existing enum-like fields.

These changes are made without a version bump. Your integration must accept them without failing.

***

## **Why is it changing?**

Until now, our documentation hasn't stated how Operators should handle new fields. Some serialisation libraries reject unknown fields by default, including Java/Jackson, where `FAIL_ON_UNKNOWN_PROPERTIES` is enabled by default. The Wallet API carries the most risk. If your wallet rejects a Hub88 request because it contains a new field, bets, wins and rollbacks can fail in production.

We're making the rule explicit so that every integration is built for it.

***

## **Impact**

* **If your integration already ignores unknown fields,** no action is needed.
* **If your integration uses strict schema validation,** a future Hub88 release that adds a field could cause your requests to fail. Common examples are Jackson with default settings, Go's `DisallowUnknownFields`, Pydantic `extra="forbid"`, and custom JSON Schema validators with `additionalProperties: false`. On the Wallet API, a failed request means a failed bet, win or rollback.

***

## ⚠️ **Action required by 15 October 2026**

Review how your integration deserialises Hub88 payloads, and make sure that:

1. **Unknown fields are ignored, not rejected.**
2. **New values in enum-like fields are handled where possible.** Map an unrecognised value to a safe default.
3. **`X-Hub88-Signature` is verified against the raw request body.** Always verify the signature against the exact bytes you received, before deserialising. If you deserialise first and then re-serialise the object to verify it, any unknown fields you drop will change the body, and signature verification will fail.

After 15 October 2026, Hub88 will continue to add optional fields as described above. An integration that rejects unknown fields may fail when those fields are released.

***

If you have any questions or need support updating your integration, please contact your Hub88 account manager or our technical support team.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hub88.io/api-changelog/october-2026/operator-api-your-integration-must-ensure-forward-compatibility.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.