Aggregators

Aggregator integration

Aggregators distribute KOI games to many brands through one integration. There are two ways to connect.

Option 1: KOI API on behalf of your brands

You integrate the KOI API exactly as an operator does, with your own partner account, and route each session and callback to the right brand on your side.

Step	You do
Launch	Call `request-access` with the brand's player ID and put the brand reference in `extra_data`.
Callbacks	Receive every bet, win, bonus win and rollback on your four endpoints. Read `extra_data` to find the brand, then forward to its wallet.
Answer	Return the brand wallet's `old_balance`, `new_balance` and `operator_tx_id` to KOI.

Everything in the Wallet callbacks section applies to you. You are responsible for signature verification, idempotency and timeouts between KOI and your brands.

Read Brands & routing for the recommended routing setup.

Option 2: KOI implements your protocol

If you already have a game-provider protocol, KOI can connect to it through a dedicated adapter. KOI then follows your launch, wallet and signature rules instead of the ones in this documentation.

Adapters already exist for several aggregators. To start a new one, send your account manager:

your provider integration specification and its version;
sandbox credentials and endpoints;
the currencies, languages and markets you need.

KOI validates the adapter end to end in the sandbox before go-live.

Free-bet bonuses through an adapter: when a bonus ends, KOI sends your wallet a zero-amount bet followed by a win with the bonus total, both with the same transaction ID. Rounds of the bonus send nothing. If your protocol has a native free-round method, KOI can use it instead.

Which option to choose

	Option 1	Option 2
Your effort	Implement the KOI API once	None beyond configuration
Time to market	Depends on your team	Depends on the KOI adapter
Protocol	KOI	Yours
Best for	Aggregators onboarding several new providers	Aggregators with an established provider protocol