Relay Integration Guide
Integration of an external game with casino wallets through the relay service. The guide covers onboarding, the launch flow, the round lifecycle, the API surface available to a game game provider, error handling, casino configuration and reporting.
Purpose of the relay
The relay sits between a game and every casino the game is offered on. A game never learns a casino's wallet URL or a player's wallet credential:
- The launcher receives the player from the casino, creates a session and redirects the browser to the game with a
sessionId. - The game backend calls the relay with that
sessionIdand the game provider's token. The relay resolves the session, finds the casino and forwards the money movement. - The relay records every round and every money movement, so both the game provider and the platform can audit them.
Terminology
| Term | Meaning | In the API |
|---|---|---|
| Game provider | The studio, partner or aggregator integrating with the platform. Owns one or more games and holds the game provider token. | group, groupId |
| Game provider token | The game provider's service-to-service credential, rly_<slug>_<secret>. Shown once when issued. Sent on every relay call. | service token |
| Game | A registered title with a numeric gameId (always greater than 100), a name and a frontendUrl. | game, gameId |
| Game backend | The server-side component of the game that holds the token and calls the relay. | — |
| Casino | The operator whose wallet holds the player's money. Registered by the platform, not by the game provider. | provider, providerId |
| Platform | The operator of the launcher and the relay. The platform team performs registration and provides support. | — |
| Launcher | Platform service that receives a player from a casino, creates the session and redirects the browser to the game. | — |
| Relay | Platform service the game backend calls. Resolves the session, forwards money movements to the casino wallet, and records rounds and transactions. | — |
| Session | One player, one game, one casino, one currency. Created by the launcher, valid for one day, referenced by sessionId. | sessionId |
| Cash-out | A debit: money leaves the player's wallet. This is the bet. It opens a round. | /api/balance/cash-out |
| Cash-in | A credit: money returns to the player's wallet. A win, a refund, or a zero-amount loss settlement. It settles the round. | /api/balance/cash-in |
| Round | The relay's record of one bet and its settlement, keyed by (providerId, roundId). | roundId |
| Transaction | One money movement, keyed by (providerId, transactionId). A repeat of the same key returns the stored result. | transactionId |
Cash-out takes money out of the casino wallet (a bet). Cash-in puts money back (a win or refund). This is the reverse of how the words are often used inside a game. Every page of this guide uses the wallet's meaning.
Integration summary
The platform team registers the game provider and its games and issues a game provider token. A casino launches a player; the launcher redirects the browser to the game's frontendUrl with a sessionId. The game backend validates the session with the relay, reads the balance, places a bet with cash-out, settles it with cash-in, and announces the end of a game round with round-ended where the casino requires it. The game provider can read back its rounds and transactions, and read what each casino has configured for its games.
Generated API reference
Each environment serves a generated OpenAPI reference at /api/docs on its base URL: development and staging; see Environments. These pages, like the relay itself, are only reachable from whitelisted IP addresses. This guide explains the flow and the rules; the generated reference is the authoritative field-by-field schema for the exact version deployed.