Launching a game
Reading the catalog, starting a session with POST /sessions, opening the launch URL and reissuing it.
The launch API has three routes. All of them are signed as described on Authentication and signing, and all paths are relative to the RGS host issued with your keys.
| Route | Scope | Answers |
|---|---|---|
GET /catalog/games | catalog | 200 a page of games, or 304 |
POST /sessions | launch | 201 a session and its launch URL |
POST /sessions/{id}/launch-url | launch | 200 a new launch URL for a session |
Your games are grouped in markets. A market belongs to your casino and fixes the countries and currencies it
serves, its games and their versions, its bet levels and its stake limit. Market ids are given to you at onboarding
(for example gb).
The catalog
GET /catalog/games?market=gb&limit=50| Parameter | |
|---|---|
market | required. One of your market ids |
limit | optional. Games per page, 1 to 200; 200 if absent |
cursor | optional. The nextCursor of the previous page |
{
"items": [
{
"id": "slots",
"title": "Slots",
"type": "slot",
"status": "active",
"variant": "957",
"rtpPpm": 957000,
"maxWinMultiplier": 5000,
"features": ["free_spins", "multipliers"],
"bets": { "GBP": { "min": 200000, "max": 2000000, "default": 1000000 } },
"media": { "thumbnail": "https://cdn.example.com/media/slots.svg" },
"build": "1.0.0",
"updatedAt": "2026-11-01T00:00:00Z"
}
],
"nextCursor": "c2xvdHM"
}| Field | |
|---|---|
id | the game id you pass to POST /sessions |
title, type | display name and kind (such as slot). A game with no catalog details is listed with its id as the title |
status | always active today |
variant | the RTP variant this market runs |
rtpPpm | the published RTP of that variant, in parts per million: 957000 is 95.7 %. It comes from the game's math setup, the same figure the game's rules show. 0 for a game whose math this RGS does not run |
maxWinMultiplier | the largest win as a multiple of the stake |
features | feature tags; an empty list when there are none |
bets | by currency: min, max and default stake in micro-units. These are the market's figures; a player's own limit can narrow them at launch |
media.thumbnail | image URL |
build | the game version the market runs |
updatedAt | when the listing last changed |
Games come in id order. Keep requesting with cursor until a page has no nextCursor. A page can hold fewer than
limit games and still have a nextCursor, because a game whose math is not published is left out of the catalog
(it could not be launched either); do not stop at a short page.
Caching
Every 200 carries an ETag, which changes only when that page's content does. Send it back in If-None-Match and
the RGS answers 304 Not Modified with no body when nothing changed. Several tags and * are accepted, and a weak tag
(W/"...") compares like a strong one.
Errors
| Status | error | details.reason | Meaning |
|---|---|---|---|
| 400 | ERR_VAL | body | the request body is unreadable or larger than 1 MiB |
| 400 | ERR_VAL | market | market is missing |
| 400 | ERR_VAL | limit | limit is not a number from 1 to 200 |
| 400 | ERR_VAL | cursor | not a valid cursor |
| 400 | ERR_ATE | market | no such market for your casino (another casino's market reads the same) |
| 401 | ERR_ATE | see refusals | signing, scope or address |
| 500 | ERR_GEN | ours; retry |
Starting a session
POST /sessions{
"requestId": "launch-7f3a",
"marketId": "gb",
"gameId": "slots",
"mode": "real",
"player": { "id": "p-1001", "country": "GB", "currency": "GBP", "maxStake": 1000000 },
"lang": "en",
"device": "desktop",
"onOpenSession": "new",
"returnUrl": "https://casino.example.com/lobby"
}| Field | |
|---|---|
requestId | required. Your id for this launch, unique for your casino. See idempotency |
marketId | required. One of your markets |
gameId | required. A game of that market |
mode | optional, real if absent. Stored with the session; no other value changes anything today, so leave it out |
player.id | required. Your player id; the RGS sends it back to your wallet as playerId |
player.country | required. One of the market's countries, as configured for it (for example GB) |
player.currency | required. One of the market's currencies |
player.maxStake | optional. The player's own stake limit in micro-units; 0 or absent is none |
lang, device | optional. Passed through to the game client in the launch URL |
onOpenSession | optional, new if absent. new closes the player's open session in this game and starts a new one; resume keeps it when it can. See Resuming an open session |
returnUrl | optional. Stored with the session |
Unknown fields are ignored.
A 201 answers:
{
"sessionId": "019a4c6e-3b7d-7c2e-9f10-5b6a7c8d9e0f",
"launchUrl": "https://cdn.example.com/slots/1.0.0/index.html#api=https%3A%2F%2Frgs.example.com&device=desktop&lang=en<=Jx3...",
"launchExpiresAt": "2026-11-04T00:01:00Z",
"gameVersion": "1.0.0",
"variant": "957",
"schemaHash": "5d41402abc4b2a76b9719d911017c592..."
}When a session was resumed (see below), the answer also carries "resumed": true. The
field is absent for a new session.
sessionId, gameVersion and variant are what the answer's session runs. schemaHash is present only for a release that has a schema
set, and is for the game client; you can ignore it.
What the RGS checks
In this order, and the first failure answers:
requestId,player.idandgameIdare present, thenmarketId, thenonOpenSessionisnew,resumeor absent.- A repeated
requestIdis answered here from the session it started, and none of the checks below run: see Repeating a request. - The market exists and is yours.
player.countryis one of the market's countries, andplayer.currencyone of its currencies.- The game is on the market.
- Certification. Unless the player has an unfinished round in this game, a real market takes new sessions only while your wallet has a current pass of the conformance suite (see Conformance and going live). Whether you can use a market for testing before then is agreed at onboarding. A player with an unfinished round is not refused for certification, so they can come back to finish it.
- The game's math is published for the variant.
- Stake limit. The session's bet levels are frozen now: the market's levels that are not above
min(market stake limit, player.maxStake). If no level is left, the session is refused. The default bet is the market's default when it survives, otherwise the smallest level left. The levels do not change for the life of the session. - The game's client and schema must have passed their check. If they have not, the answer is
500 ERR_MAINTENANCE(reasonfrontorschema), even for a player with an unfinished round; retry later.
Unfinished rounds
If the player left a round of this game unfinished, the new session runs that round's version, variant and math, not
the market's current ones, so the player finishes the round on the game it started on. gameVersion and variant in
the answer tell you which.
One session at a time
Starting a new session closes the player's previous session of the same game. On a market with one_game_at_a_time
(the UK's RTS 14C rule), it closes the player's previous session of any game. With onOpenSession set to resume
the previous session of the same game can be kept instead: see Resuming an open session.
Resuming an open session
onOpenSession says what to do with the player's open session in the game.
| Value | What happens |
|---|---|
new | The default, also when the field is absent. The open session is closed and a new one starts. Use it for the usual case: one launch, one session |
resume | The open session is kept when it can be, and gets a new launch URL. Use it when your lobby reopens a game the player already has open (another tab, or a reload on your side) and you want to keep that session rather than cut it off |
Any other value is refused with ERR_VAL, reason on_open_session.
With resume, the open session is kept when the player has one in this game, it has not idled out, and a new session
would equal it. That means a new session would start with the same market, currency, game version, variant, math, bet
levels and limits, mode and country. If the market's version or stake limit has changed since the session started, or
the player's maxStake gives a different limit now, it is not the same session and a new one starts. Otherwise resume starts a
new session exactly as new does. It never causes a refusal.
A resumed session answers with its own sessionId, a new launchUrl and "resumed": true. It keeps its start time.
The launch URL you held before stops working if it was not opened yet; a client already playing in the session keeps
playing. The new URL is an ordinary launch URL: it works once, for 60 seconds.
On a market with one_game_at_a_time, an open session in another game is not resumed: the new session closes it.
A resume request does not reserve its requestId. Send it again and it resumes again, with a fresh link. A
requestId of a call that started a session is still answered from that session, as in
Repeating a request.
Repeating a request
requestId makes POST /sessions safe to retry. Send the same body again with the same requestId and, while the
player has not yet opened the session, you get the same sessionId with a fresh launch URL; the URL from the earlier
answer stops working.
A repeat gets the first request's answer. It is answered from the stored session right after the required fields
are checked, before the market, country, game, certification, stake and release checks, so a change of
configuration in between does not refuse it, and it runs the first answer's gameVersion and variant. The session
keeps the first request's values: the repeat's mode, player.country, player.maxStake, lang, device and
returnUrl are not read.
The same requestId is refused with ERR_VAL, reason request_id, when its player, game, market or currency
differ from the first request, or once the session has been opened or closed. To launch again after that, use a new
requestId.
Errors
| Status | error | details.reason | Meaning |
|---|---|---|---|
| 400 | ERR_VAL | body | body unreadable, larger than 1 MiB, or not JSON |
| 400 | ERR_VAL | (empty) | requestId, player.id or gameId missing |
| 400 | ERR_VAL | market | marketId missing |
| 400 | ERR_ATE | market | the market is unknown or not yours |
| 400 | ERR_LOC | country | the player's country is not the market's |
| 400 | ERR_VAL | currency | the market does not offer the currency |
| 400 | ERR_VAL | game | the game is not on the market, or its math is not published |
| 400 | ERR_WALLET_NOT_CERTIFIED | wallet | your wallet has no current conformance pass |
| 400 | ERR_GLE | stake_limit | the stake limit is below the smallest bet |
| 400 | ERR_VAL | on_open_session | onOpenSession is neither new nor resume |
| 400 | ERR_VAL | request_id | the requestId belongs to another launch, or its session was opened or closed |
| 401 | ERR_ATE | see refusals | signing, scope or address |
| 500 | ERR_MAINTENANCE | front, schema | the game's client (front) or schema (schema) has not passed its check; retry later |
| 500 | ERR_GEN | ours; retry with the same requestId |
A 400 is final: the same request gets the same answer. A 500 has details.retryable: true, and its message never
says more than "service is unavailable"; quote its requestId to us.
The launch URL
Send the player's browser to launchUrl exactly as you received it, by redirect or in an iframe. Do not rebuild it.
Everything the game client needs is in the URL's fragment (after #), which browsers do not send to servers or put
in Referer headers:
| Fragment key | |
|---|---|
lt | the launch token |
api | the RGS address the client talks to |
lang, device | your lang and device, possibly empty |
The launch token works once, and only for 60 seconds (launchExpiresAt). The game client exchanges it for
the session when it starts; after that the URL is spent. Create the session when the player chooses the game, not in
advance.
A new launch URL
POST /sessions/{id}/launch-url{ "lang": "de", "device": "mobile" }The body is optional; an empty field keeps the session's value. A 200 answers with the same fields as
POST /sessions and a new token, valid for 60 seconds; the previous unused token stops working.
This works only while the session has not been opened. Once the player has opened it, a new URL is refused with
ERR_IS, reason launched; to put the player back in the game, start a session with a new requestId: with onOpenSession resume it
keeps the open session when it can, otherwise it starts a new one.
| Status | error | details.reason | Meaning |
|---|---|---|---|
| 400 | ERR_VAL | session_id | the id is not a UUID |
| 400 | ERR_VAL | body | body unreadable, larger than 1 MiB, or not JSON |
| 400 | ERR_IS | (empty) | no such session of your casino, or it is closed |
| 400 | ERR_IS | launched | the player already opened the session |
| 401 | ERR_ATE | see refusals | signing, scope or address |
| 500 | ERR_GEN | ours; retry |