Launching games

Real-money launch: `POST /v1/game/url`

You call this when a player clicks a game in your lobby. We return a single-use URL; you redirect the player's browser to it.

{
  "product": "runecode", "publisher": "wizards", "game": "royal-tiger-v2",
  "user": "player-48213", "token": "9f0c1d2e-5a7b-4c3d-8e1f-0a1b2c3d4e5f",
  "currency": "USD", "language": "en", "device": "desktop", "tag": "real"
}

Field	Required	Notes
`product`, `publisher`, `game`	yes	the three slugs from the catalogue, copied verbatim. Never build or split them yourself
`user`	yes	your player id: opaque, stable per player, at most 128 characters. Do not mint a new one per launch
`token`	yes	one-time session token, at most 256 characters (a UUID is recommended). Comes back as `token` on every wallet call of this session; the player's browser never sees it
`currency`	yes	upper case; must be enabled for you
`language`	no	BCP-47, default `en`; unknown values fall back to `en`
`device`	no	`desktop` (default), `mobile`, `tablet`
`tag`	no	`real` (default), `affiliate`, `streamer`, `employee`, `qa`. Non-`real` tags are accepted only for users you pre-registered, are excluded from production accounting and are reported separately

Response:

{ "url": "https://play.<rgs-domain>/l/9b2c…", "fair": true }

url is single use, valid about 120 seconds, and redirects once to the game. It carries session material: never log it.
fair says whether the session's math supports provably-fair verification.

Rules worth knowing

Retries are safe. A byte-identical repeat of a launch request within 10 minutes, before the URL has been opened, returns the same response. The same token with a different body is 409 ERR_TOKEN_REUSED. You can also send an Idempotency-Key header (1 to 255 visible ASCII characters): the same key and body returns the stored response for 24 hours; the same key with a different request is 409 ERR_IDEMPOTENCY.
No wallet call happens at launch. Your wallet's balance is read when the game opens, so a slow wallet does not fail the launch. If your wallet is marked degraded, the launch answers 503 ERR_MAINT instead of a URL that would fail on the first spin.
The game's release is fixed at launch and never changes during the session.
Framing: the game is served with a CSP that allows only the lobby origins you registered. Register every origin before going live.
Jurisdiction: an operator enabled for one jurisdiction profile resolves to it. An operator with several must send country (ISO 3166-1 alpha-2) on every launch, or have a complete brand-to-profile map. Anything we cannot resolve is refused (400 ERR_JUR), never guessed. Countries on the platform deny list are refused (403 ERR_JUR).

Optional fields (extensions)

Safe to omit. Send the header RuneCode-Extensions: v1 to receive extra fields in the response (runecode.sessionID, expiresAt, the resolved release and jurisdiction, a request id). brand, country, ip, links, session, metadata and timestamp are accepted as described in the specification. responsibleGaming and displayCurrency are refused with 400 until implemented rather than silently ignored.

Demo launch: `POST /v1/game/url/demo`

Play money, no wallet, no token reaches you.

{ "product": "runecode", "publisher": "wizards", "game": "royal-tiger-v2", "currency": "USD", "language": "en", "device": "desktop" }

Response { "url": "…" }. Demo sessions are signed with a separate demo key, rate-limited per player IP, and never reach any wallet.

After the launch

When the player opens the URL the game authenticates against the RGS, which calls your wallet's /v1/balance with your token. From then on every bet is a /v1/debit and every payout a /v1/credit: see Implementing the wallet.

Errors

HTTP	`code`	Meaning
400	`ERR_BAD`	not JSON, schema violation, unknown enum value, field too long
400	`ERR_NAV`	the game has no approved release for your operator, jurisdiction or currency
400	`ERR_CUR`	currency not enabled for you
400	`ERR_JUR`	jurisdiction cannot be resolved
401	`ERR_ATE`	missing or invalid signature, unknown operator, revoked key, stale timestamp
403	`ERR_FBD`	operator suspended, source IP not allowed, endpoint not enabled for you
403	`ERR_JUR`	blocked in the player's country or jurisdiction
404	`ERR_GNF`	unknown game, or not approved for you
409	`ERR_TOKEN_REUSED` / `ERR_IDEMPOTENCY`	see the rules above
429	`ERR_RATE`	rate limit; honour `Retry-After`
503	`ERR_MAINT`	maintenance or bets paused; honour `Retry-After`