Changelog
Changes to the Operator API v1, newest first.
- ChangedThe wallet test suite calls with a UUID session_id, writes amounts in the precision of the run's currency, and has a 20th case, rollback_win: our rollback of a win you credited must take it back. currency_mismatch now passes any refusal, and a bet taken from a balance in the other currency; it fails only when the money leaves this currency's balance. bonus_amount passes as a string or a number.
- ChangedThe reference wallet takes back a win it is told to roll back, refuses a win that arrives after its rollback, accepts both secrets during a rotation (AGG_SECRET with a comma) and reads amounts to DECIMALS places.
- FixedPOST /v1/sessions refuses a locale over 20 characters and a lobby_url over 500, and POST /v1/games/{id}/demo a locale over 10, with 422 VALIDATION_FAILED naming the field. They used to reach the provider gateway and come back as 409 GAME_UNAVAILABLE.
- FixedGAME_UNAVAILABLE now means only a game: it answers launches, demos, grants and campaigns. A refusal by the service behind any other call (rates, invoice estimate, transactions, rounds, sessions, jackpots, live tables) is 422 VALIDATION_FAILED with the reason in message and fields empty; it used to come back as 409 GAME_UNAVAILABLE.
- DocumentedGET /v1/games: volatility, paylines, game_format, hit_rate, max_win, release_date, jackpot and certified_markets, which the answer already carried.
- DocumentedGET /v1/invoices/estimate: what your invoice would say if it were drawn now, for the month so far or a period you name.
- DocumentedKey rotation: your calls to us are accepted with the old key for 48 hours, but our calls to your wallet are signed with the new key within a minute. A provider rollback may name a win; undo whichever movement it names.
- FixedThe OpenAPI wallet schema: transaction_id and bonus_amount in your answer are read as a string or a number, round_id on getbalance is always empty, and free_spins_id is kept on our own rollback of a free-spin movement.
- AddedGET /v1/free-spins/buy-ins lists the bought features a free spin of a game may open with, each with its price as a multiple of the stake. POST /v1/free-spins takes an optional buy_in_id from that list, on exactly one game, and the grant answers it back. Endorphina games offer them as Bonus Pop.
- AddedPOST /v1/bonus-campaigns/{id}/cancel ends an active campaign early where its game provider can; GET /v1/bonus-campaigns/options says so in cancellable. A campaign ended this way reads status cancelled.
- Added01.tech games take buy_bonus campaigns, on one game per campaign, and they can be cancelled. The win of a bought bonus reaches your wallet as a win with free_spins_id equal to the campaign_id.
- AddedGET /v1/games: each game carries the studio’s details — volatility (1–5), paylines, game_format, hit_rate (%), max_win (× bet), release_date (first of the month), jackpot — null where the studio does not publish them, and certified_markets, the jurisdictions the studio has certified the game in. certified_markets closes nothing; restricted_countries still does.
- AddedGET /v1/free-spins/bet-options takes optional brand and player_id. A provider that keeps an account per brand answers the stakes of that brand's account; without brand, the brand of the player's latest session is taken, then yours — as for POST /v1/free-spins.
- ChangedMancala free spins are granted on one game per grant and can be cancelled: POST /v1/free-spins/{id}/cancel withdraws an active Mancala series. A Mancala series becomes finished, with finished_at, once its last spin is paid.
- AddedPOST /v1/free-spins takes the same optional brand: { code, domain } as POST /v1/sessions. A provider that keeps an account per brand places the series under that brand's account, where the game opens; without brand, the brand of the player's latest session is taken, then yours.
- ChangedGET /v1/free-spins/bet-options lists the stakes Mancala publishes for the game; a grant at another stake is refused with FREE_SPINS_REFUSED naming the accepted ones. A Mancala series becomes finished, with finished_at, once the provider reports its last spin.
- AddedPOST /v1/sessions takes an optional brand: { code, domain }, the brand of yours the player plays on. Providers that keep an account per brand open the game under that brand's account; a brand without one, or a session without brand, opens under yours. brand.code is required when brand is sent; brand.domain is a bare host name.
- AddedErrors METHOD_NOT_ALLOWED (405) and UNSUPPORTED_MEDIA_TYPE (415), retryable: false, in the usual error body. An unknown path answers NOT_FOUND in the same body.
- ChangedUNAUTHORIZED is only an unknown or revoked key, a signature that does not verify or a timestamp outside the window. A key we cannot check because the service holding keys is unavailable answers UPSTREAM_UNAVAILABLE, retryable: true. So does a launch every provider refused for the moment; no session is left open and a repeat is safe.
- ChangedGET /v1/games: an unknown type or a cursor that did not come from this listing answers 422 VALIDATION_FAILED naming the field, not GAME_UNAVAILABLE.
- ChangedWallet: bonus_amount and transaction_id in your answer are read as a string or a number; any other form counts as the field left out, and a bet answered with a readable balance is no longer rolled back for it. balance stays a string.
- ChangedWallet: our rollback after silence carries the free_spins_id of the movement and its amount in the currency's precision. getbalance always has an empty round_id and no game_id. One call to your wallet has 25 seconds with its retries, so a wallet_timeout above 25 seconds is not used in practice.
- ChangedGET /v1/transactions/{id}: a movement is kept for at least 180 days, not for exactly 180. Older ones may still answer; do not rely on a 404 after 180 days.
- DocumentedGET /v1/games: next_cursor is null on the last page, and every game carries free_spins, whether a free-spin grant can be placed on it now. Images URLs mostly point at our image storage host rather than GET /v1/images/{id}.
- DocumentedGET /v1/free-spins/providers lists the providers whose games take grants. A grant can also be pending or failed; a repeat of a failed grant places it again, and only an active grant can be cancelled.
- DocumentedGET /v1/rounds/{id} answers an empty transactions list for a round we do not know, not NOT_FOUND. POST /v1/sessions is not idempotent: a repeat opens another session.
- DocumentedBonus campaigns: the buy_bonus type, campaign_limit and min_cashout_multiplier. section_code on games.
- DocumentedWallet: our calls are signed with the newest active key. A provider rollback of a bet that never settled with your wallet reaches you as a getbalance, and an ordinary win for a refused or rolled-back round is not passed on; only awards arrive without a bet. Our own rollback is retried like any call and, after a silent win, takes the win back.
- DocumentedWallet: free_spins_id is also on provider rollbacks of a series. The test suite fails response_time at 3 seconds.
- AddedPOST /v1/sessions takes an optional player_name, up to 32 characters: the nickname other players see in multiplayer games (Callisto Minis). Never send a real name; without it the game shows its own pseudonym.
- AddedRATE_LIMITED answers carry Retry-After: whole seconds until the next calendar minute starts, from 1 to 60.
- ChangedA body that is not valid JSON, or a field or query parameter of the wrong JSON type, answers 422 VALIDATION_FAILED in the usual error body, with the field named in fields ("body" when the JSON does not parse). It used to be HTTP 400 in a different format.
- ChangedAn unexpected failure on our side answers HTTP 500 with UPSTREAM_UNAVAILABLE and retryable: true in the usual error body. Every refusal from /v1 now has the same shape.
- AddedGET /v1/bonus-campaigns?player_id= lists the campaigns of one player, newest first, at most 100 — for a support agent asking what a player has been given. Exactly one of reference and player_id; both or neither answers 422 VALIDATION_FAILED.
- AddedGET /v1/live-tables: Live Casino tables on your games as they stand now — open or closed, dealer, limits in the currency you ask for, players and seats, recent results. Pragmatic Play for now.
- AddedBonus campaigns: POST /v1/bonus-campaigns places free spins, a fortune wheel, a treasure chest or a golden dragon for your players, set off by first launch, bet amount, spin count or loss amount. GET /v1/bonus-campaigns/{id}, GET /v1/bonus-campaigns?reference= and GET /v1/bonus-campaigns/options?game_id=. New error BONUS_CAMPAIGN_REFUSED and sandbox value sandbox_player_bonus_refused.
- DocumentedPOST /v1/debug/signature answers key, timestamp, payload and signature blocks alongside the diagnosis; the OpenAPI file now describes them. The whole spec is checked against the live sandbox.
- Addedagg-wallet-suite.mjs runs the wallet test suite from your CI with a JUnit report and an exit code, and reference-wallet.mjs is a wallet that passes it. See Wallet test suite.
- AddedSandbox scenario values: a player_id, game_id or player_country that makes the sandbox answer PLAYER_BLOCKED, GAME_RESTRICTED_IN_COUNTRY, GAME_UNAVAILABLE, NO_DEMO, FREE_SPINS_REFUSED or UPSTREAM_UNAVAILABLE on demand. See Testing.
- AddedThe wallet test suite: POST /v1/test/wallet-validation and GET /v1/test/wallet-validation/{id} on the sandbox run the whole wallet contract against your wallet_url.
- AddedPOST /v1/debug/signature on the sandbox: every step of a signature check and the common mistake it matches. Also in the operator portal under Validation.
- DocumentedSignature test vectors.
- AddedAn address allowlist per operator, set under Credentials in the operator portal. A signed call from an address outside a non-empty list answers 403 ADDRESS_NOT_ALLOWED.
- AddedGET /v1/jackpots and GET /v1/jackpots/winners.
- DocumentedVALIDATION_FAILED answers HTTP 422; earlier versions of this guide said 400.
- DocumentedWallet game_id is the game provider code, not the catalogue id; the mapping goes through session_id.
- DocumentedThe complete wallet error contract, rate limits, and wins that arrive for a refused bet.
- DocumentedMoney fields that are JSON numbers today: jackpot amounts, invoice webhook figures, rates.
- Deprecatedstudio_code on games and providers and the studio_code query filter. Use provider_code.
- Addedsections, regulated and tier_mode in GET /v1/rates.
- Addedmarket and rates_by_market in GET /v1/rates.
- AddedInvoice webhook: invoice.issued and invoice.voided with the PDF inline.
- AddedOptional bonus_amount in the wallet answer to bet and win.
- AddedGET /v1/rates.
- ChangedGames are titles: id names the title, provider_code the brand.
- AddedGET /v1/providers; images on games (portrait, cover) and providers (symbol, horizontal); unsigned GET /v1/images/{id}.
- Addedcountry filter on GET /v1/games, restricted_countries on each game, GAME_RESTRICTED_IN_COUNTRY on sessions and demos.
- AddedPOST /v1/games/{id}/demo and NO_DEMO.
- AddedPOST /v1/free-spins, GET /v1/free-spins/{id}, GET /v1/free-spins?reference=, POST /v1/free-spins/{id}/cancel, GET /v1/free-spins/bet-options.
- Addedfree_spins_id on wallet bet and win calls.
- AddedGET /v1/ping.
- Addedplayer_country, player_ip, player_device and deposit_url on POST /v1/sessions.
- AddedPublic API on its own host: GET /v1/games, POST /v1/sessions, POST /v1/sessions/{id}/close, GET /v1/transactions/{id}, GET /v1/rounds/{id}.
Documented marks behaviour that already existed and was not written down before.
