Core Concepts

Session & Launch

A game client is born from a launch URL and authenticates every request with the session token baked into that URL.

Launch URL

The operator calls POST /operator/launch (server-to-server) and receives a launchUrl to embed as an iframe. The RGS builds it as:

{iframeBase}/{slug}?sessionToken={token}&id={gameCode}[&lobbyUrl={url}]
Param Description
slug (path) The game's slug — dice, plinko, blackjack, … Used to route to the right client.
sessionToken Bearer token for every /game/*, /seed/*, and /session/* call.
id The full game code, including RTP suffix (e.g. dice-alpha). See Game Codes & RTP.
lobbyUrl Optional. Where a "back to lobby" control should send the player.

The client reads sessionToken from its own URL on boot and sends it as Authorization: Bearer <token> on every request:

const params = new URLSearchParams(window.location.search);
const token = params.get("sessionToken");

The token is opaque — the client never decodes it. It maps server-side to one player + game + currency, which is why the /game/play body never names the game.

Resuming on Load — /game/current

A round can be open when the client (re)loads — a refresh mid-Mines, a dropped connection. Call /game/current on boot to fetch the balance and any in-progress round before rendering.

POST /game/current
Authorization: Bearer <token>

{
  "balance": "104.00",
  "active": true,
  "roundId": "9f1c…",
  "gameId": "mines-alpha",
  "roundData": { "amount": "1.00", "mineCount": 3, "gridSize": 25 },
  "state": { "active": true, "mineCount": 3, "rounds": [ { "field": 7, "multiplier": "1.08" } ] }
}
  • active: false (and no round fields) means there's nothing to resume — start fresh.
  • state is the client-safe game state. Sensitive data is stripped — e.g. for an active Mines round the unrevealed mines array is withheld until the round ends.
  • If a bet is mid-initialization the endpoint briefly polls, then returns 503 round_initializing if it can't settle. Retry shortly.

Single-action games (Dice, Plinko, …) never have a resumable round — each bet opens and closes a round in one call. /game/current still returns the balance, which is handy on load.

Round Details & History

  • GET /game/round/{roundId} — full details for one round: RoundDetails (id, amount, result, active flag), the Seed (server hash, client seed, nonce — plus the revealed serverSeed once the pair is retired), and the game state. Shape is per-game (RoundResponse).
  • GET /game/history?limit=10 — recent completed rounds for this player + game, newest first. Each entry is { id, wager, payout, multiplier, createdAt }. limit is 1–100 (default 10).
  • GET /game/balance — current balance, fetched live from the operator wallet.

Keeping the Session Alive

Sessions expire after 1 hour of inactivity and are scoped to one player + game + currency. Re-launching the same player and game returns the existing active session.

POST /session/refresh rotates the token and extends expiry by 1 hour:

{ "sessionToken": "<new-token>", "expiresAt": "2026-06-22T15:04:05Z" }

Swap in the returned token for subsequent requests. A session can only be refreshed once per token (a second attempt returns 409); always use the latest token you were given.

Previous
Message Protocol
Next
Game Flow