Games Integration

This guide documents the contract between a game client (the front-end that runs inside the iframe) and the Jackpot RGS — how a game sends bets and receives results, resumes interrupted rounds, and lets players verify outcomes.

It covers the classic games: Dice, Limbo, Plinko, Keno, Wheel, Baccarat, Mines, Blackjack, Hilo, and Towers.

This is the client side of the integration. Operator concerns — launching sessions, wallet callbacks, HMAC auth — are documented separately in the RGS operator docs.

The Model

Every game is a thin front-end that talks to the RGS over a handful of REST endpoints. The client never computes outcomes. It sends the player's intent (a bet, an action) and renders whatever the RGS returns. All money movement, RNG, and game math happen server-side.

sequenceDiagram
    participant Operator as Operator Backend
    participant RGS as RGS API
    participant Client as Game Client (iframe)

    Operator->>RGS: POST /operator/launch
    RGS-->>Operator: { sessionToken, launchUrl }
    Operator->>Client: Embed iframe at launchUrl

    Note over Client: read sessionToken from URL
    Client->>RGS: POST /game/current  (resume?)
    RGS-->>Client: { balance, active round, state }

    Client->>RGS: POST /game/play  { message }
    Note over RGS: debit → run game → credit
    RGS-->>Client: { message: result, roundId }

    Client->>RGS: POST /game/verify  (provably fair)
    RGS-->>Client: { message: recomputed result }

The Endpoints

Every endpoint below is authenticated with the session token as a bearer token. Base URL is the RGS host (e.g. https://rgs-staging.jackpot.studio).

Endpoint	Method	Purpose
`/game/play`	POST	Place a bet or take a game action. The workhorse — every game uses it.
`/game/current`	POST	On load, fetch balance + any in-progress round so the client can resume.
`/game/round/{roundId}`	GET	Fetch full details + state for one round.
`/game/history`	GET	List the player's recent completed rounds.
`/game/balance`	GET	Current player balance.
`/game/verify`	POST	Re-run a past result from its seeds (provably fair).
`/seed/current` · `/seed/rotate` · `/seed/reveal` · `/seed/upcoming`	POST	Manage the player's provably-fair seed pair.
`/session/refresh`	POST	Extend the session before it expires.

How to Read This Guide

Start with the core concepts, then jump to the page for your game:

Message Protocol The /game/play envelope and the protobuf-JSON message inside it Game Flow Single-action vs multi-action games, and how rounds resume Provably Fair Seeds, the commit-reveal scheme, and verification

Message Protocol