232rgs — API documentation

Regeneration (2 November 2026, latest 5 November 2026): the OpenAPI document, the endpoint index, the field reference, the HTML and the PDF now describe the source commit named on the cover and in source-identity.json (196 operations on 5 November): every route the RGS serves with every optional module configured, read from the code. Request schemas are the handlers' own validators. Where a delta below says the generated reference still describes the September source, this regeneration replaces that. The client, operator, wallet and showcase chapters were re-checked against the routes on 5 November 2026 (w21); the deltas below are kept as history.

October 24 delta (Claude lane, not yet integrated): - Tequity wallets: the Tequity free bets API lets them add and remove free bets and list free-bet amounts. - Tequity wallets (connector): a wallet that speaks Tequity's protocol can launch its players and take their wagers and wins (Tequity wallet): /authenticate, /balance, /transaction with resends, and /cancel, per-session bet limits, and free rounds named by the wallet's campaign. Jackpot games on these sessions come later. - Free rounds in the browser wallet API: /wallet/authenticate and /wallet/play list the session's freeRounds, and /wallet/play takes freeRoundId (client API). - BetSymphony: a declined wager now cancels its round and answers ERR_IPB. Before, the player got an internal error and the round stayed pending. - Time-outs: the operator time-out is in Operator API, the player time-out in Client API. Self-exclusions and time-outs now block every account of the player, and responses carry the new limit fields (timeOutUntil, playBlockedUntil, pending). - Back office: the back-office routes are also explained in backoffice.md.

M0 implementation delta: History cursors, private interactive replay, live multiplayer entitlements, safe RG limits and request-time wallet destination policy supersede the affected behavior below. The generated September OpenAPI/HTML/PDF remain historical and are not republished by this module.

October 5 audited-owner delta: Current account provisioning and entitlement ownership documents bounded post-authentication SQL and HTTP 503 CONTROL_PLANE_BUSY with Retry-After: 1. Provisioning duplicates remain action no-ops; repeated successful entitlement PUTs still write and audit. Mutation/audit rollback and response normalization are preserved. The source-pinned September OpenAPI/HTML/PDF and portal remain historical, unchanged and not republished or certified by this local slice.

October 5 campaign delta: Current campaign ownership, retries and pagination supersedes this historical edition's campaign behavior. /v1/campaigns now supports bounded limit/cursor pages and explicit HTTP 409 when a legacy unpaged history exceeds 100 grants; exact grant retries return the original ledger balance, including ended campaigns. Read/create/status and grant unavailability use their documented HTTP 503 envelopes. The September generated OpenAPI/HTML/PDF and documentation portal remain pinned and have not been regenerated, republished or certified by this local implementation slice.

October 1 platform delta: the reference and generated OpenAPI/HTML/PDF below remain pinned to their September source, not the latest platform tree. The Phase 0 successor removes /metrics from the gameplay listener. Operations use a separate internal memory-only endpoint, default 127.0.0.1:9464/metrics; it returns 503 before first collection or once the snapshot expires. See metrics operations and limits. This runtime task does not republish or certify the separate documentation portal.

Current service reference · 21 September 2026

October 1 one-shot transaction delta: the local successor also returns native HTTP 503 with { "error": "MONEY_PATH_BUSY" } and Retry-After: 1 for bounded money-transaction unavailability. Recover/resend only with the original command identity and canonical body; a lost COMMIT acknowledgement is not proof of rejection. /wallet/play retains its Stake HTTP-200 ERR_UE envelope with Round status unavailable; reconcile before retrying, not automatic fresh-wager retry. See one-shot budgets and exclusions. The generated September reference/portal has not been republished by this runtime slice.

Generated reference source: the commit named on the cover and in source-identity.json (5 November 2026)
Prose chapters written against: ed208c392fd33d563ed095cd5ffe95f474abda21
Last source change at the prose chapters' commit: bubblebeam11 — “lobby: resolve African tiles from mounted game assets”

232rgs is a remote gaming service with persistent player sessions, game-version-pinned execution, wager settlement, wallet accounting, round history and replay. This reference describes the API implemented at the source revision above. It is intended for BetSymphony's engineering team and other integrators reviewing the current service.

This is a description of the current API, not a proposed replacement contract or a future-work document. Examples use synthetic identifiers and balances. The showcase uses synthetic credit; its login is separate from the operator API credentials described below.

Reading order and files

The repository-root openapi.json is a supplied BetSymphony Platform API document. It is not the 232rgs API. The 232rgs specification is this directory's openapi.json.

1. Service boundaries

Operator / platform backend
  ├── Bearer operator API key ──> 232rgs /operator/v1/*
  │                               accounts, launch, entitlements, wallet administration
  └── delivers the game URL + launch token to the player's browser

Player's game client
  ├── SDK titles ──> 232rgs /wallet/* and /bet/event
  │                  sessionID in JSON; six-decimal integer amounts
  └── Native client ──> /v1/authenticate, then Bearer session token
                        /v1/* and /v2/*; currency-minor-unit integer amounts

External-wallet mode (separate from the showcase's custodial mode)
  232rgs ── signed HTTP requests ──> operator-hosted wallet
  operator-hosted wallet ── signed callbacks ──> /wallet/v1/callbacks/{operatorCode}

The two /wallet surfaces are different protocols: /wallet/authenticate is the browser-facing SDK adapter; /wallet/v1/callbacks/{operatorCode} is an Ed25519-signed server-to-server callback. They do not share authentication or money units.

Addresses

Use the exact API host rather than the lobby URL for RGS calls. The service does not return a complete frontend launch URL from /operator/v1/launch; it returns a token. Frontend hosting assembles the game URL.

HTTP conventions

• JSON over HTTPS, UTF-8. Ordinary JSON request bodies use Content-Type: application/json.
• Signed inbound callbacks use application/vnd.23rgs.wallet-callback+json; their exact bytes are signed. Preserve that media type and the 23rgs signature domain names verbatim.
• Maximum RGS request body: 65,536 bytes. Larger bodies return HTTP 413.
• Normal application success is 200; creation routes may return 201; callback admission and unsettled native rounds may return 202; some close/revoke routes return 204 without a body. Each endpoint defines its own statuses.
• Timestamps returned by application services are ISO 8601 strings unless a field explicitly states UNIX seconds. Signed-wallet header timestamps are decimal UNIX seconds.
• Identifiers are opaque. UUIDs, external player IDs, game codes, remote transaction IDs and client command IDs are distinct namespaces.
• The native player and operator request schemas are strict: an extra field is rejected with 400 INVALID_REQUEST (since w21 for every one of them). Partner-protocol surfaces stay as tolerant as their protocols need: the browser wallet bodies (/wallet/*, /bet/event) accept and ignore extra fields, and the signed wallet callback reads its four X-Wallet-* headers among the others a request carries. The individual schemas show which is which.
• There is no global Idempotency-Key HTTP header contract. Idempotency lives in named JSON identifiers documented per endpoint.

2. Authentication

Operator keys and scopes

An operator key has the opaque form <key-uuid>.<secret>. Keys are operator-scoped. An expired, revoked, malformed, wrong-scope or suspended-operator key fails authorization. The HTTP API returns 401 OPERATOR_AUTHENTICATION_FAILED for these operator authorization failures, rather than a separate OAuth scope response.

The authorization header must start with the exact case-sensitive prefix Bearer. A missing header or wrong prefix returns 401 AUTHENTICATION_FAILED before the operator-specific key check.

Supported HTTP-issued scopes are keys, launch, wallet, campaigns, responsible-gaming, reconciliation, games and disputes. The OpenAPI operation extension x-operator-scope identifies the required scope. Keys are created by an already-authorized operator using /operator/v1/api-keys; this is not a public operator-registration API. Keep keys server-side. The key-management endpoint returns the new token once in its response.

Launch and session lifecycle

1. The operator account/currency and game entitlement exist.
2. The platform backend requests a launch token for its playerId, currency, gameCode and locale.
3. The token expires after 300 seconds. A native first authentication consumes it once and creates a session pinned to the selected game version.
4. Native authentication returns a distinct session bearer. SDK authentication binds the launch token as its browser sessionID; subsequent SDK calls reuse that binding.
5. Sessions have an eight-hour upper bound, shortened by configured responsible-gaming session limits. Authorization also checks revocation, operator state, self-exclusion and pinned game-version availability.
6. Native /v1/session/close revokes that native session. SDK /wallet/end-round acknowledges already settled presentation; it is not session logout.

Do not exchange the same launch token through both native and SDK authentication flows. Choose the flow used by that client.

3. Money and modes

For EUR, a displayed 1.00 is native/operator 100, but SDK 1000000. Conversion is exact; do not pass a native 100 to the SDK edge expecting one euro. Currency syntax is three uppercase ASCII letters, but syntactic acceptance is not automatic game or currency support. The SDK conversion helper contains EUR, USD, GBP, CAD, AUD and CHF at two decimal places, and JPY/KRW at zero. The current SDK title configurations are constructed for two-decimal currencies; the showcase uses EUR.

Where an integer is a JSON number, it must remain within JavaScript's safe integer range, at most 9007199254740991. Positive amount requirements and additional game/account limits still apply. Do not silently round decimals into valid requests.

SDK base amount versus charged stake

POST /wallet/play receives the base amount, a mode, and the currency. The RGS applies the configured mode costMultiplier to calculate the debit. Payout is derived from the selected authored book using the base amount. The authoritative wallet amount in the response is balance.amount; the monetary payout is round.payout.

Example for a 1.25 ante mode: base amount 2000000 means EUR 2.00, while the charged stake is EUR 2.50 (native 250). The product must be representable in whole currency minor units. Unknown modes, currency/game mismatches and nonrepresentable charges are rejected. Read config.betLevels and config.betModes returned by authentication rather than inventing a universal bet menu.

SDK round.state contains the selected game's authored event sequence. Render it; do not use it to calculate or submit settlement. A payoutMultiplier or event amount is not interchangeable with six-decimal currency amounts. The current SDK one-shot edge settles during /wallet/play; /wallet/end-round does not issue another winning credit. A custodial round answers round.active: false. For a provider session (an external operator served through an adapter, such as BetSymphony) a win answers round.active: true although it is paid, and the next /wallet/play answers ERR_BE until the client calls /wallet/end-round (client-api.md). A stopped or refused wager on the browser routes is ERR_GE with HTTP 200, not the native API's 403 WAGER_NOT_ALLOWED.

Native play uses the pinned game's action contract. A native wager.amount is the charged wager amount, not a generic SDK base-amount alias. For book-backed slot games, the action encodes the mode and base minor amount (for example ante:200), while the wager contains the exact mode-adjusted charge. Do not mix the browser and native request schemas.

4. Server-to-server quick start

These are illustrative requests for a configured operator. They are not commands automatically executed against the showcase. RGS_API and OPERATOR_KEY below stand for the supplied API address and your server-side key; placeholders must be replaced with issued credentials through your normal secret management.

4.1 Create or retrieve the currency account

POST /operator/v1/accounts
Authorization: Bearer <operator-key>
Content-Type: application/json

{"playerId":"player-demo-001","currency":"EUR"}

The account is scoped by authenticated operator, external playerId and currency. Provisioning an account does not itself deposit funds. The route returns 201 on creation or 200 when returning an existing account.

4.2 Enable a game for the operator

PUT /operator/v1/games/fish_4_fish
Authorization: Bearer <operator-key>
Content-Type: application/json

{"enabled":true,"currencies":["EUR"]}

This updates the operator's entitlement to an already registered game. It does not upload or register game code. The static title identifiers are listed in the showcase chapter.

4.3 Fund a custodial account

POST /operator/v1/wallet/transactions
Authorization: Bearer <operator-key>
Content-Type: application/json

{"playerId":"player-demo-001","externalTransactionId":"demo-funding-001","kind":"deposit","amount":10000,"currency":"EUR"}

Use this only for the custodial account flow. externalTransactionId identifies the funding operation and must be retained for safe retry. Reusing it for a different operation conflicts. An external-wallet operator instead uses the separate signed-wallet protocol; the SDK showcase client operates in custodial mode.

4.4 Issue a launch token

POST /operator/v1/launch
Authorization: Bearer <operator-key>
Content-Type: application/json

{"playerId":"player-demo-001","currency":"EUR","gameCode":"fish_4_fish","locale":"en"}

Successful response shape (illustrative token placeholder):

{"launchToken":"<issued-launch-token>","expiresInSeconds":300}

Locale is implemented as two lowercase letters with an optional uppercase region, such as en or en-GB. Build a frontend URL using the returned token. SDK clients expect sessionID and rgs_url; the showcase additionally includes lang and lobby_url.

https://<frontend-host>/games/fish_4_fish/?sessionID=<url-encoded-launch-token>&rgs_url=<url-encoded-rgs-origin>&lang=en

4.5 SDK client authentication and play

POST /wallet/authenticate
Content-Type: application/json

{"sessionID":"<issued-launch-token>","language":"en","gameId":"fish_4_fish"}

Retain sessionID. Read the returned balance, configuration and any round data. The SDK then submits a permitted base amount:

POST /wallet/play
Content-Type: application/json

{"sessionID":"<issued-launch-token>","amount":2000000,"currency":"EUR","mode":"BASE","gameId":"fish_4_fish"}

Check both HTTP status and status.statusCode. Stake-compatible domain failures can be HTTP 200 with a non-SUCCESS status. A 200 alone is not successful play. After presenting the returned result, /wallet/end-round uses {"sessionID":"<issued-launch-token>"}.

Native alternative

A native client exchanges its own launch token at /v1/authenticate, then sends the resulting bearer to native endpoints. /v2/play uses a lowercase UUID-v4 commandId, action, wager and client seed. /v2/recover takes the same canonical body and ID and never creates absent work. See the client chapter for complete request and recovery rules.

5. Retry and settlement semantics

• Operator funding: retry the same externalTransactionId and identical operation. Lookup is available under /operator/v1/wallet/transactions/{externalTransactionId}.
• Native v1 play: the canonical request includes externalRoundId and wager.id. Reusing an accepted identity with changed content conflicts.
• Native v2 play/recovery: persist the commandId and canonical body before sending. Retry/recover the same identity; do not manufacture a new wager after a lost response. Recovery is scoped to the authenticated operator/account/game, including the supported replacement-session path.
• SDK /wallet/play: this current edge generates a new server-side round identity for each request. It does not expose the native v2 caller-command idempotency contract. A network timeout is not permission to blindly resubmit the same SDK wager as a new call.
• External wallet: use the stable operation identity, authenticated lookup and signed callback protocol described in the wallet chapter. A timeout or pending/unknown result is not a proved decline.
• Interactive commands: start, action and recovery have their own sequence/identity envelope. They are separate from one-shot SDK settlement.
• HTTP 202: inspect the response body. It can mean an accepted callback, a pending round settlement, or an unresolved external balance request; it is not a universal success result.

6. Shared errors, rate limiting and browser behavior

Most native/operator failures use {"error":"CODE"}. Validation failures can add details containing Zod issues. Some settlement and external-balance errors also carry a round or operation identifier. Exact endpoint responses are in the reference and OpenAPI.

Requests are limited by client address until their credential verifies, then by the credential: 120 requests a minute per effective client IP for requests without a verified credential (none, or one that failed or was forged), shared across replicas; then a verified session counts 120 a minute per player, a verified operator key (a console user's key too) 1,200 a minute per key, and all verified requests from one address together at most 6,000 a minute. Browser wallet and native-game routes through the lobby relay keep the relayed budget (10,000 a minute per relay address, plus their per-session limits). A refusal is 429 RATE_LIMITED with retry-after; a shared limiter that cannot answer gives 503 RATE_LIMIT_UNAVAILABLE. Liveness and readiness are exempt, and metrics are on their own listener. Forwarded addresses are trusted only for configured trusted proxies. These are server limits, not a promised throughput SLA.

Wildcard browser CORS is installed only for the exact paths /wallet/authenticate, /wallet/balance, /wallet/play, /wallet/end-round and /bet/event. Those paths advertise GET,POST,OPTIONS and Content-Type, X-Api-Key, Authorization; preflight responds 204. The business operations themselves are POST, not GET. Native/operator routes and signed callbacks do not receive this wildcard CORS policy. Listing X-Api-Key in allowed CORS headers does not turn it into operator authentication: operator routes use a bearer.

7. Health and metrics

Readiness checks PostgreSQL and the entrypoint's configured dependencies (including Redis and runtime/key coverage); the default readiness deadline is two seconds. Health does not identify an exact deployed source commit. /metrics is an operational surface, not a gameplay endpoint; its access boundary can be enforced by deployment networking.

8. Runtime availability and versioning

The normal service registers operator, custodial, campaign, responsible-gaming, one-shot client and multiplayer features. External connector configuration/execution routes are registered only when the external signing runtime is configured; interactive routes are registered only when the pinned interactive runtime is loaded. The OpenAPI includes these implemented conditional routes and describes their registration conditions. An absent conditional route returns the framework's 404, not a fabricated future API response.

SDK games are pinned to release catalog versions and math-library identities. A static title listing does not override operator entitlements or the authentication response. Sessions and accepted work retain their pinned game version. Public wire identifiers inherited from 23rgs are intentional compatibility identifiers.

This document's version is its source revision. Later code revisions can change the reference; the revision above remains the authority for this edition. Internal deployment tooling, database administration and the separate game-authority service are not additional operator-facing RGS HTTP endpoints.

Showcase service and SDK title catalog

Implementation: ed208c392fd33d563ed095cd5ffe95f474abda21 · 21 September 2026 · titles and lobby routes re-checked on 5 November 2026 (w21, 78cf205a)

Showcase hosts

• Lobby and game assets: https://232rgs-lobby.fly.dev
• RGS API: https://232rgs.fly.dev

The lobby is a separate authenticated web application, not the operator API. It uses a synthetic-credit account for each signed-in user. It provisions that account, applies its configured limits, credits it once using an idempotent funding identity, and requests ordinary RGS launch tokens server-side. Operator API keys are not sent to the browser.

The game frontend receives the RGS launch token in sessionID, the API origin in rgs_url, and presentation parameters lang and lobby_url. The game calls the SDK API documented in Client API. These are real persistent RGS rounds using synthetic balances, not calls to a BetSymphony wallet.

Current title identifiers

The list below is the static registry in games/sdk-slot/src/index.ts, not a claim that every game is entitled to every operator. Seven entries have version 1.0.2, Propagandalf 1.0.1. Use the exact catalog code for gameCode in operator launch requests and gameId in SDK play requests. Display titles, catalog codes and math package names are not interchangeable.

SDK mode lookup uppercases the incoming name; responses use the canonical upper-case mode. Library configuration must match the registered modes and costs. The game server selects the outcome; a client does not submit an outcome, payout or replacement math package through these APIs.

These SDK title configurations use two-decimal currencies. The normal display bet levels are 0.10, 0.20, 0.50, 1, 2, 5, 10, 20, 50, 100. For Wild 4 Fish and Meowbach Wilds, 0.10 and 0.50 are omitted because the 1.25× mode cannot charge those bases in whole minor units. This is reflected in each authentication response's six-decimal config.betLevels.

Always use the returned configuration and permitted amounts for the launched game. A title's catalog maximum payout is a book-unit policy, not a currency amount or a client settlement instruction. round.payout and balance.amount remain authoritative monetary outputs.

Lobby HTTP interface (separate host)

These routes belong to the showcase frontend service, not the RGS OpenAPI. No additional game-list or JSON launch API is implied.

The lobby also serves GET /admin, POST /admin/{action}, GET /play/{code}, GET /bet/replay/{game}/{version}/{mode}/{event} and its own files under /lobby-assets/ (tools/demo-lobby.mjs); they are not documented here yet.

Lobby authentication and transport details

• The cookie is lobby_session, HttpOnly, SameSite=Lax, Path=/, with a twelve-hour lifetime. HTTPS sets Secure.
• Without a session, an HTML-accepting GET receives 303 to /login?next=...; other requests receive 401 {"error":"SIGN_IN_REQUIRED"}.
• The request Host must match the configured lobby origin, except for /health/live; mismatch returns 403 {"error":"DEMO_LOBBY_ORIGIN_REQUIRED"}.
• Body limit: 4 KiB. Request timeout configuration: 30 seconds.
• Default limiter: 600 requests/minute per effective IP. Login POST: 10/minute. Launch GET: 60/minute. Liveness, login GET and game assets are exempt from the limiter.
• Normal pages/responses use Cache-Control: no-store. Static assets use no-cache, or private, max-age=31536000, immutable for immutable asset paths.
• Upstream failures handled by the lobby return 502 {"error":"DEMO_LOBBY_UPSTREAM_UNAVAILABLE"}. Other handled client errors return their 4xx status with {"error":"INVALID_REQUEST"}.

Operational observation for this edition

On 21 September 2026, a read-only request to https://232rgs.fly.dev/health/ready returned HTTP 200 with {"status":"ready"}. An unauthenticated non-HTML lobby request returned HTTP 401. These observations confirm those HTTP responses at the time checked; they do not bind the running image to the source revision. No login, launch, wager or wallet operation was performed against the public showcase while preparing this documentation.

Source: tools/demo-lobby.mjs, games/sdk-slot/src/index.ts, apps/rgs/src/main.ts, packages/core/src/stake-wallet-edge.ts.

232rgs client API

M0 implementation delta: History cursors, private interactive replay, live multiplayer entitlements, safe RG limits and request-time wallet destination policy supersede the affected behavior below. The generated reference (openapi.json, index.html and the PDF) is regenerated from the code (MAINTAINING.md).

Documented source: ed208c392fd33d563ed095cd5ffe95f474abda21 — bubblebeam11 (21 September 2026); re-checked against the routes on 5 November 2026 (w21, 78cf205a).

This chapter documents the client-facing routes registered by apps/rgs/src/app.ts and the WebSocket upgrade installed by apps/rgs/src/main.ts. The RGS serves 31 client HTTP operations: 26 native /v1 or /v2 operations and five browser wallet operations. The hand-written September fragment documents 23 of them; the other eight are GET /v2/state, GET /v1/free-rounds (free rounds), POST /v1/responsible-gaming/time-out (below), POST /v2/interactive/skip, GET /v1/interactive/rounds/{id}/replay, GET /v1/jackpots/{poolId}, GET /v1/engagement/tournaments/{id}/leaderboard and POST /v1/engagement/tournaments/{id}/participation, all in the endpoint index. The WebSocket is intentionally documented here as a protocol, not as a synthetic HTTP operation.

All JSON bodies are limited to 64 KiB. Invalid JSON or a failed request schema returns 400 {"error":"INVALID_REQUEST"}; oversized bodies return 413, unsupported media types return 415, and the limiter can return 429 {"error":"RATE_LIMITED"} with retry-after: 120 requests a minute per player once the session verifies, 120 a minute per client address before (README §6). Every native /v1 and /v2 request schema (body, query and path parameters) is strict: an unknown field is rejected with 400 INVALID_REQUEST. Since w21 that includes /v1/authenticate, legacy /v1/play and its wager, and the /v1/history query, which used to strip unknown fields; a route that takes no query parameters does not read the query. Browser wallet bodies explicitly pass unknown fields through, although only documented fields are used. Integer money must be a non-negative/positive JavaScript safe integer as required by the individual operation; do not send decimal JSON numbers.

Credentials, units, and registration

Session bearer

Native client routes that require a session use Authorization: Bearer <sessionToken>. Tokens issued by authentication are opaque base64url values. A valid session is active, unexpired, tied to an active/draining game version, belongs to an active operator, is not self-excluded, and is within the maximum-session limit. Rejection is 401 AUTHENTICATION_FAILED.

POST /v1/authenticate consumes a one-time launch token and returns the session token. Launch tokens are opaque, 43–128 characters at the HTTP boundary, and cannot be reused. Session tokens pass the same 43–128 character boundary check. Do not put either token in URLs or logs.

Money

Native /v1 and /v2 monetary fields (balance, wager.amount, payout, campaign grant amounts) are integer currency minor units. The game/account currency is a three-uppercase-letter code. The caller must use the session currency for a wager; game-specific configured limits decide which actions and values are accepted.

Browser wallet amounts use a separate integer six-decimal Stake scale. The adapter supports EUR, USD, GBP, CAD, AUD, CHF (two decimals) and JPY, KRW (zero decimals). Internal minor units × 10^(6 − currency decimals) = browser amount. Thus EUR 100 internal cents is 1,000,000; a EUR amount must be divisible by 10,000. Inputs that cannot be represented exactly return the browser protocol error ERR_GE, in an HTTP 200 response.

Conditional routes

The base app always registers authentication, balance, session close, and reality-check routes. The OpenAPI fragment marks optional registrations with x-registration-condition:

• rounds: browser wallet routes, /v1/play, history/replay/fairness, /v2/play, /v2/recover and /v2/state.
• interactive: /v2/interactive/* and /v1/interactive/rounds/{id}/replay.
• campaigns, responsibleGaming, and multiplayerLobby: their respective client routes.

The production entrypoint supplies rounds, campaigns, responsible gaming, and multiplayer lobby. Interactive routes are installed only when an interactive runtime registry is available.

Native HTTP API

Establish and close a session

POST /v1/authenticate has no bearer authentication. Submit:

{"launchToken":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

A successful custodial response is:

{
  "sessionToken":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "balance":2500,
  "currency":"EUR",
  "gameId":"8e94d65b-1205-48fe-b992-4d6bdce3764c",
  "walletMode":"custodial"
}

For an external-wallet operator, balance is null; currency and game ID remain present. A launch token is consumed atomically, so retrying after a lost success response cannot issue another session and returns 401.

GET /v1/balance returns { "balance": 2500, "currency": "EUR" } for a custodial session. With an external wallet, an approved provider lookup returns the same shape; an unknown or pending lookup returns 202 {"status":"unknown"|"pending","operationId":"uuid"} and an unavailable/declined lookup returns 502 {"error":"EXTERNAL_BALANCE_UNAVAILABLE","operationId":"uuid"}. POST /v1/session/close revokes the caller’s current active session and returns 204; repeating a close with that token is 401.

Reality checks and responsible gaming

GET /v1/reality-check returns due, nullable nextAt, and a non-negative integer elapsedSeconds. Acknowledgement is only valid when the check is due: POST /v1/reality-check/acknowledge returns { "nextAt": "2026-09-21T12:30:00.000Z" }; otherwise it is 401.

New wagers and room allocation are rejected with 423 {"error":"REALITY_CHECK_REQUIRED"} when a check is due. GET /v1/responsible-gaming returns every limit, using null for unset values. POST /v1/responsible-gaming/self-exclude accepts a date-time until between one day and five years from processing. It returns the resulting ISO timestamp and revokes all active sessions for the account; use the returned timestamp as the effective boundary, because a request may not shorten an existing exclusion.

Time-out: POST /v1/responsible-gaming/time-out takes the exact body {"period":"24h"|"7d"|"30d"|"42d"}. - Effect: it blocks every account of the player for that period and ends their sessions; it never shortens a longer block. - Response: the limits object, including selfExcludedUntil, timeOutUntil, playBlockedUntil (when play is allowed again) and pending (raised or removed limits waiting for their 24 hours, else null). - Self-exclusion also blocks every account of the player, including accounts opened later.

One-shot play and recovery

POST /v1/play is the legacy external-round-id interface. Its externalRoundId and nested wager.id are caller-controlled, 1–128 characters. The same external round ID under the same session must have an exactly identical canonical request (action, wager ID/amount/currency, client seed); an identical retry returns the durable result, while different content returns 409 ROUND_CONFLICT. It is session-bound, so use /v2 for recovery through a replacement session.

POST /v2/play is the client-command interface. Its required commandId is a lowercase UUIDv4. The command is account-scoped and game-scoped, and its payload is canonically hashed. Identical retries, including with a replacement session for the same account and game, return the original result without a second wager. A reused command ID with a changed action, wager, currency, or seed returns 409 ROUND_CONFLICT. Different command IDs are distinct wagers even if all other payload fields match.

POST /v2/recover never admits a new wager. It uses the same body as /v2/play, returns the accepted result when available, and returns 404 ROUND_NOT_FOUND if that account/game has no accepted command. It can recover accepted work after the accepting session expires or the operator stops accepting new work, provided the caller holds a suitable account/game session.

All successful one-shot plays return:

{
  "roundId":"6fb10568-605b-4662-8ebd-b85f24408a12",
  "payout":200,
  "balance":10100,
  "state":{"gameOwned":true},
  "fairness":{
    "commitment":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "serverSeed":"abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "algorithm":"hmac-sha256-v1"
  }
}

state is game-owned JSON and has no common fixed shape. A game can reject invalid action/wager configuration as 400; insufficient custodial funds are 422 INSUFFICIENT_FUNDS; admission policy, including a safety stop of any scope (global, operator, market and the rest) or a violated outcome-monitor model, is 403 WAGER_NOT_ALLOWED; a responsible-gaming monetary limit is 423 RESPONSIBLE_GAMING_LIMIT.

For external-wallet sessions, an accepted round may not yet be financially final: 202 ROUND_SETTLEMENT_PENDING includes roundId and an internal settlement status. A declined debit yields 402 EXTERNAL_WALLET_DECLINED. Retry the same accepted /v1 request or use /v2/recover; do not replace the identifier with a new wager. A credit rejection moves the accepted outcome to manual review rather than voiding it.

Round history, replay, and fairness

GET /v1/history?limit=20 returns most-recent-first account history. limit defaults to 20 and must be 1–100. The answer is {rounds, nextCursor, hasMore}: send nextCursor back as cursor (opaque, 1–512 characters) for the next page; it is null on the last one. settledAt is null until settlement. The current serializer emits a numeric payout in every history item, including an unsettled row.

GET /v1/rounds/{roundId}/fairness returns the persisted algorithm, draw ID, commitment, client seed, nonce (string), and revealed server seed for an owned round. A non-owned round or a round without an available revealed proof returns 404 ROUND_NOT_FOUND.

GET /v1/rounds/{roundId}/replay returns stored history plus verification. Verification is matched, mismatch, or unavailable. A mismatch is deliberately returned as HTTP 409 with the full replay body; unavailable verification is HTTP 200 and names REPLAY_INPUTS_UNAVAILABLE or REPLAY_RUNTIME_UNAVAILABLE. history.state, event payloads, stored result state, and recomputed state are game-owned JSON. Available verification includes compared, with boolean checks requestHash, transcript, result, payout, state, and commitment; missing-runtime verification can include its lookup key as gameVersion.

Campaign visibility and multiplayer room selection

GET /v1/campaigns returns grants already associated with the session account, newest first, as {grants, nextCursor}. Without limit or cursor it answers up to 100 grants, and 409 CAMPAIGN_PAGINATION_REQUIRED when the account has more; with limit (1–100, default 50) or cursor it pages, and nextCursor names the next page (an invalid cursor is 400 INVALID_CAMPAIGN_CURSOR). Each grant has grantId, campaignId, campaign code, integer amount, currency, and grantedAt.

POST /v1/multiplayer/room takes an empty object (or no body) and returns a waiting/running room for the session’s active multiplayer game version, such as {"roomId":"uuid","status":"waiting"}. A single-player or unavailable game is 404 MULTIPLAYER_GAME_UNAVAILABLE. It also requires a non-due reality check.

Interactive games

Interactive routes use native integer minor units and session bearer authentication. They expose a projection, never internal game state, seed, account ID, session ID, runtime configuration, or receipt records.

• POST /v2/interactive/start: lowercase UUIDv4 commandId, positive wager, and 1–1024 byte client seed. It debits once and is idempotent only for the exact account/game/wager/seed binding.
• POST /v2/interactive/action: lowercase UUID roundId, new UUIDv4 command ID, expectedSequence 0–63, and an action matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}. Repeating the same accepted command is acknowledged with duplicate: true; a conflict is 409 INTERACTIVE_COMMAND_CONFLICT.
• POST /v2/interactive/recover: start command ID only. It is read-only recovery and returns 404 INTERACTIVE_EXECUTION_NOT_FOUND when unavailable in the caller’s account/game scope.

A projection contains fixed fields format: "interactive-player-v1", commandId, roundId, game, wager, sequence, complete, nextActions, cumulativePayout, settlementStatus, and nullable payout. settlementStatus is active, credit-owed, or settled: a complete round may be credit-owed until internal liability completion occurs. Runtime absence/identity mismatch is 503 INTERACTIVE_RUNTIME_UNAVAILABLE.

Browser wallet API

The five browser endpoints accept a body sessionID, rather than a bearer token. Browser-facing CORS permits all origins, GET, POST, OPTIONS, and Content-Type, X-Api-Key, Authorization; preflight receives 204. Unknown request properties are accepted at this boundary, but documented fields are the only ones used.

POST /wallet/authenticate either binds a fresh launch token as sessionID, or resumes an existing browser binding. language (2–16 characters) is remembered for an existing binding; gameId (1–128 characters) is accepted but does not select or validate a different game in the current implementation. It serves custodial operators, and external-wallet operators only through an adapter whose provider takes the session's money (docs/design/operator-adapters.md); any other external operator gets ERR_GE (external operator is not enabled). A successful response contains a six-decimal balance, config, and, if the persisted progress is active, a round.

{
  "sessionID":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "language":"en",
  "gameId":"coin-flip"
}

{
  "status":{"statusCode":"SUCCESS","statusMessage":"Success"},
  "balance":{"amount":25000000,"currency":"EUR"},
  "config":{
    "gameID":"coin-flip","minBet":100000,"maxBet":100000000,"stepBet":100000,
    "defaultBetLevel":1000000,"betLevels":[100000,200000,500000,1000000],
    "betModes":{"BASE":{"mode":"BASE","costMultiplier":1,"feature":false}},
    "jurisdiction":{"socialCasino":false,"disabledFullscreen":false,"disabledTurbo":false,"disabledSuperTurbo":false,"disabledAutoplay":false,"disabledSlamstop":false,"disabledSpacebar":false,"disabledBuyFeature":false,"displayNetPosition":false,"displayRTP":false,"displaySessionTimer":false,"minimumRoundDuration":0}
  }
}

POST /wallet/balance returns the currently bound session balance. POST /wallet/play requires a non-negative six-decimal amount, uppercase currency, non-empty mode, and optional game ID. Amount must become a positive aligned internal amount; a configured mode can apply an exact cost multiplier. The response uses the charged base amount in round.amount, the computed payout in round.payout, and all balance/payout fields use six decimals.

Free rounds (2026-10-24): POST /wallet/authenticate and a successful POST /wallet/play list the session's free rounds for this game and currency under freeRounds, soonest-ending first, up to 20. Each entry is {id, remaining, amount, mode, endsAt}, with amount in six decimals and mode BASE. The field is absent when there are none. - Playing one: send freeRoundId with /wallet/play, in that mode, at that amount. Nothing is charged, and the win is paid as the campaign's payout category. - Refusals (ERR_GE): a free round sent at another amount or mode is ERR_GE (free round unavailable for this play). An ended or used-up grant is ERR_GE with the engine's reason. - Operator set-up: an operator with an external wallet needs the free-rounds and free-rounds-external modules. Free rounds through a Tequity wallet are listed in tequity-wallet.md.

Current browser play generates its own round and client seed. It has no caller-provided command ID or client idempotency key. A client that loses a /wallet/play response cannot use that endpoint to prove which generated command was accepted; it must not blindly issue another play. One-shot browser play settles during /wallet/play; state is an event array when supplied by the game, otherwise an adapter-generated reveal/total/final-win array. - Custodial operators: every round answers round.active: false. - Provider sessions (an external operator served through an adapter, such as BetSymphony): a losing round answers round.active: false, but a win answers round.active: true although it is already paid. The next /wallet/play answers ERR_BE (player already has an active bet) until the client calls POST /wallet/end-round, which pays nothing more. The Stake web-sdk calls end-round after a win; a client of its own must do the same. - A play the edge never finished (a provider session whose wallet call is still pending, or whose answer was lost) is resumed by the next /wallet/authenticate: the same round and wallet calls, never a new wager. A play refused with an error status has ended and is never resumed.

POST /bet/event stores an opaque event cursor string (default "0") for existing progress and returns it. It does not submit an economic wager. POST /wallet/end-round returns a durable already-settled custodial result even after the normal session is unavailable, if the browser binding and matching settled round remain available; otherwise it authorizes the binding normally. It cannot authorize new play.

Browser protocol failures from the edge are deliberately HTTP 200, with both status and error:

{
  "status":{"statusCode":"ERR_GE","statusMessage":"invalid stake amount"},
  "error":{"code":"ERR_GE","message":"invalid stake amount"}
}

Codes are ERR_IS invalid session, ERR_IPB insufficient balance, ERR_GLE gambling/reality limit, ERR_BE active-bet or round conflict, ERR_BNF no tracked bet, ERR_GE invalid/game/wager problem (including a refused wager: a safety stop of any scope, a violated outcome-monitor model or RNG quarantine is ERR_GE wager is not allowed, where the native API answers 403 WAGER_NOT_ALLOWED), and ERR_UE when the round's or session's status cannot be known yet (a provider transaction still pending, the money path or control plane busy, or the provider session unavailable): reload or reconcile before retrying, never send a new wager. Browser routes can still return ordinary HTTP 400 for malformed transport input, 429 for rate limiting, or 500 for unhandled errors.

Multiplayer WebSocket protocol

Upgrade GET /v1/multiplayer to WebSocket; it is not an OpenAPI HTTP operation. In the production entrypoint, origin checking is required in production and compares the Origin exactly against configured allowed origins. A missing required or disallowed origin receives an HTTP 403 before upgrade. Non-production configurations may permit an absent origin, but a supplied origin must still belong to the allowed set.

The client must send one text JSON authentication message within 5 seconds (default):

{"type":"authenticate","sessionToken":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","roomId":"a3182b82-5d64-4d5e-aebc-4f9ef591b221","afterSequence":0}

afterSequence defaults to 0, must be an integer from 0 through Number.MAX_SAFE_INTEGER, and is used for both public and private recovery cursors. Binary frames are unsupported. Authentication failures send {"type":"error","error":"AUTHENTICATION_FAILED"} then close with code 4401; an unmet reality check similarly sends REALITY_CHECK_REQUIRED and closes because authentication did not complete. Authentication timeout also closes 4401.

On success, one or more snapshots are sent. A normal snapshot is:

{"type":"snapshot","roomId":"a3182b82-5d64-4d5e-aebc-4f9ef591b221","status":"waiting","state":{"phase":"ANTE"},"sequence":0,"events":[],"privateEvents":[]}

events contain {sequence,type,payload} where payload is game-owned public JSON; privateEvents contain {sequence,payload} and are only for the authenticated account. Recovery pages at most 1,000 public events. If more remain, the snapshot additionally includes currentSequence and hasMore: true; the transport continues pages internally until caught up. Catch-up is bounded: a cursor more than 1,000 events behind the room (the transport's maximumCatchUpEvents, default 1,000) is not replayed. The server sends one snapshot with the room's current state, its latest page of events (public and private) and historySkippedThrough, the last sequence that was not replayed. The client renders from state; a hidden-information client asks for its private view again (the tables client's look). Normal reconnects, up to the bound, replay every missed event.

After authentication, send command frames:

{"type":"command","clientCommandId":"join-1","command":{"roundId":"round-7","action":"main","wager":{"id":"wager-7","amount":1000,"currency":"EUR"},"params":{"clientSeed":"example-seed"}}}

Command frames are strict: no extra fields at the frame, command or wager level. clientCommandId, command.roundId and wager.id are 1–128 characters; command.action is 1–64. wager is optional; when present it requires id, positive safe-integer minor-unit amount, and three-uppercase-letter currency. Optional params is an arbitrary string-keyed JSON map. Currency must equal the session currency. The server responds {"type":"ack","clientCommandId":"join-1","sequence":42,"duplicate":false,"status":"accepted"}. Reusing the same ID with an identical payload returns the same sequence with duplicate:true; changing the payload returns COMMAND_CONFLICT. Command status is accepted, applied, rejected, expired, or cancelled. A wager is reserved/debited only when accepted before the room deadline; later commands may be acknowledged as expired.

A command the server refuses is answered {"type":"error","error":"<code>"} instead of an ack, and the socket stays open (only AUTHENTICATION_FAILED closes it, with 4401). The codes: INVALID_MESSAGE (a malformed frame, or a wager outside the game version's pinned limits), COMMAND_CONFLICT, ROOM_ACCESS_DENIED, REALITY_CHECK_REQUIRED, WAGER_NOT_ALLOWED (a safety stop of any scope, a violated outcome-monitor model, the operator's wager limits or a disabled game, or RNG quarantine: what the HTTP API answers as 403 WAGER_NOT_ALLOWED), RESPONSIBLE_GAMING_LIMIT, INSUFFICIENT_FUNDS (custodial wallet), EXTERNAL_WALLET_DECLINED (the operator's wallet declined the stake), EXTERNAL_WALLET_PENDING (the stake's debit is not resolved yet; resend the same clientCommandId, never a new one), EXTERNAL_WALLET_UNAVAILABLE (the operator's wallet connector is not usable; nothing was reserved), MONEY_PATH_BUSY and CONTROL_PLANE_BUSY (busy; resend the same command), and INTERNAL_ERROR for a fault only.

A session that stops passing authentication while connected (revoked, expired, self-excluded, its operator suspended or its game version retired) receives {"type":"error","error":"AUTHENTICATION_FAILED"} and is closed with 4401 within one session check: the transport re-checks the sessions of all its authenticated sockets in one batched query every RGS_MULTIPLAYER_SESSION_CHECK_MS milliseconds (the deployment setting; default 5,000, allowed 250 to 60,000, and the RGS refuses to start outside that range). Room events published inside that interval may still arrive. Every command also re-checks its session.

The same check re-checks room access. A socket whose room no longer admits its player receives {"type":"error","error":"ROOM_ACCESS_DENIED"} and is closed with 4401 within one check. That happens when the player's operator and the room's operator stopped sharing rooms and the player has no stake in flight there: a player with an accepted stake that is not yet settled keeps the room until it settles, and may send wagerless commands such as a cash-out, but no new stake (ROOM_ACCESS_DENIED). See docs/design/multiplayer-room-tenancy.md.

Live public delivery is {"type":"event","roomId":"uuid","sequence":43,"status":"running","broadcast":{...}}; private delivery is {"type":"private","roomId":"uuid","sequence":43,"payload":...}. These payloads are game-owned JSON. The server pings every 30 seconds by default and terminates a client that does not answer a subsequent ping. Defaults also limit frames to 64 KiB, 120 messages per 10 seconds, and 1 MiB buffered output. Limits are configurable at transport construction: rate excess closes 1008, delivery backpressure or live backlog closes 1013, and live-delivery failure closes 1011.

Current title registry

The pinned weighted SDK slot registry currently names eight titles: cherry_dream (Cherry Dream), malaga_midnight (Malaga Midnight), magma-coin-rush (Coin Island), fish_4_fish (Wild 4 Fish), meowbach_wilds (Meowbach Wilds), cherry_strike (Cherry Charge), mega-clusters (Money Bricks) and propagandalf (Propagandalf). Availability is still determined by the active pinned game version and runtime/library agreement, not this list alone. Browser configuration exposes only the version’s registered game code, configured bet levels, and modes.

Source identity: ed208c392fd33d563ed095cd5ffe95f474abda21 (September), re-checked against the routes on 5 November 2026 (w21, 78cf205a).

Operator management and custodial API

Source identity: ed208c392fd33d563ed095cd5ffe95f474abda21 (bubblebeam11, 2026-09-21). This chapter describes the routes registered by apps/rgs/src/app.ts and the return values of the current core services. It is not derived from the supplied BetSymphony Platform API specification.

Conventions

All operations use Authorization: Bearer <operator-api-key-token> and the parent document's OperatorBearer HTTP bearer security scheme. A token is keyId.secret; it is accepted only while its owning operator is active, the key is unrevoked and unexpired, and the key has the required scope (or *). A bad/missing bearer value, inactive operator, revoked/expired key, or missing scope produces 401 {"error":"OPERATOR_AUTHENTICATION_FAILED"}. Never log the returned key token or launch token.

Requests are JSON, and every operator request schema is strict: an unknown property is rejected (launch, campaign creation and campaign grants stripped it until w21). Invalid input, including a route constraint violation, is 400 {"error":"INVALID_REQUEST"}, with no details. The application body limit is 64 KiB (413 when exceeded); unsupported media types return 415. Rate limiting can return 429 {"error":"RATE_LIMITED"} with retry-after: each API key may make 1,200 requests a minute, and one client address 6,000 a minute across all its verified keys; a request whose key does not verify counts against the 120 a minute of its address instead (README §6). Unexpected failures are 500 {"error":"INTERNAL_ERROR"}.

Money values are JSON integer minor units, never decimal strings or floating-point major units, and are constrained to positive safe integers (1 through 9007199254740991) where an amount is accepted. Returned money is a JSON number (the runtime converts PostgreSQL numerics to Number); values are safe integers for the routes that enforce that bound. Currency is exactly three uppercase ASCII letters (^[A-Z]{3}$). UUIDs are canonical UUID strings unless noted. Timestamps are ISO-8601 strings emitted by Date#toISOString().

x-registration-condition in the fragment identifies the buildApp dependency condition that registers the route. The production entrypoint constructs operatorAuth, wallet, campaigns, and responsibleGaming; an embedding that omits an indicated dependency does not register that route.

Scopes and key lifecycle

The shared bearer parser requires the exact case-sensitive prefix Bearer. A missing header or wrong prefix returns 401 AUTHENTICATION_FAILED before operator-key validation. The operator-specific failure code above applies after that header parsing step.

The available route scopes are keys, launch, wallet, wallet-admin, campaigns, responsible-gaming, reconciliation, games, disputes, reports and verifier. The * scope authorizes every scope but is not accepted by the API-key creation route: that route accepts only the eleven named scopes (and not demo-lobby, the demo lobby routes' scope). Duplicate requested scopes are accepted and normalized to sorted, unique scopes in the persisted key; the returned create response intentionally does not echo scopes.

Create an API key — POST /operator/v1/api-keys (keys)

Body: label (required, non-empty string, at most 128 characters, no NUL), scopes (required array of 1–16 values from the scope list), and ttlSeconds (optional integer, 300–7,776,000; default 7,776,000 / 90 days). Success is 201 with {keyId, token, expiresAt}. token is returned only by this response. Creation against a non-active operator is 401 OPERATOR_AUTHENTICATION_FAILED. Where two people are required this route refuses with 409 TWO_PERSON_REQUIRED and the key is issued through api-key.create (Two-person changes below).

{"label":"operations-wallet","scopes":["wallet","reconciliation"],"ttlSeconds":3600}

{"keyId":"11111111-1111-4111-8111-111111111111","token":"<redacted-once-only-token>","expiresAt":"2026-09-21T12:00:00.000Z"}

Revoke an API key — DELETE /operator/v1/api-keys/{keyId} (keys)

keyId is required UUID path input. Success is 204 with no body. A key cannot revoke itself; a missing, already-revoked, inactive, expired, foreign, or self key is deliberately reported as 401 OPERATOR_AUTHENTICATION_FAILED, not as a resource-discovery response.

Game entitlement and launch

Set entitlement — PUT /operator/v1/games/{gameCode} (games)

gameCode matches ^[a-z0-9][a-z0-9_-]{1,63}$. Body is exactly {enabled, currencies}; enabled is required boolean, and currencies is a required array of 1–32 currency codes. Duplicate currencies are accepted and normalized to sorted unique values. Success 200 returns {gameCode, enabled, currencies}. Only an active game can be entitled; otherwise 404 {"error":"GAME_NOT_FOUND"}. Where two people are required, offering a game (enabled: true) refuses with 409 TWO_PERSON_REQUIRED and goes through game.entitlement (Two-person changes below); turning one off stays one key.

Create launch — POST /operator/v1/launch (launch)

Body requires playerId (1–256 characters, no NUL), currency, gameCode (same pattern as entitlement), and locale (^[a-z]{2}(?:-[A-Z]{2})?$, such as en or en-GB). Optional: brandId and marketId, both or neither (lowercase identifiers, 1–64 characters); countryCode (two uppercase letters); betLimitsOverride (below); and, for an operator an adapter serves, the casino's player token as playerToken or token (1–8,192 characters, no NUL; both at once is 400). Unknown properties are 400 INVALID_REQUEST. The account must belong to the operator and currency, the game must be active with an active version, and an enabled entitlement must include the currency. Otherwise return 404 {"error":"ACCOUNT_OR_GAME_NOT_FOUND"}. An unavailable selected version, or a game this server cannot serve, returns 409 {"error":"GAME_VERSION_UNAVAILABLE"}; a game over the operator's payout limit returns 409 {"error":"GAME_OVER_OPERATOR_PAYOUT_LIMIT"}. Success is 201 with a one-time {launchToken, expiresInSeconds:300}; each success creates a new launch token, so this operation is not idempotent.

On staging and real-money deployments, an operator in external wallet mode launches only after its wallet passed the verifier since its connector last changed (Back office, wallet verifier); otherwise 409 {"error":"WALLET_NOT_VERIFIED"}.

{"playerId":"player-042","currency":"EUR","gameCode":"heist-v2","locale":"en-GB"}

Opt-in session bet limits (C1 development contract)

POST /operator/v1/launch also accepts betLimitsOverride for explicitly pinned currency-bet-limits-v3 one-shot versions when the operator's session-bet-limits flag is enabled. The flag defaults OFF. The object is strict: optional minimum, maximum, default, maximumBonusBet (positive safe-integer minor units), maximumExposure (nonnegative safe integer), and bonusBuy (boolean). An empty object explicitly selects the version's unchanged bounds. Selected bounds must be consistent and can only tighten the immutable currency profile; the default must remain inside them, and exposure cannot fall below the version's maximum payout. No currency, payout, mode or math override is accepted.

The existing launch scope is required. launch.create audits the exact captured override, pinned immutably through the resulting session and each accepted round. Malformed, unsupported, widening or disabled-policy requests are refused; a v3 launch cannot become a playable session without this custody. BetSymphony's provider-specific launch currently rejects the field. This is per-launch tightening, not maker-checker authority to widen version policy or enable a module. Disabling the flag blocks new rounds but does not invalidate accepted retries or their replay. Legacy/v1/v2 launches omit the field and keep their existing policy. This contract is focused-tested C1 work, not a production activation or deployment.

Currency and market policy successors (C1 development contract)

V4 and V5 retain the same default-OFF session-bet-limits flag and launch custody. V4 requires a version-owned currency-policy-v1 registry (integer precision 0–8) and exact versioned rational FX snapshot. FX is reporting/display only; no wager, balance or settlement conversion occurs. Legacy currency precision cannot change. Native RGS authentication/replay exposes this pinned policy. The Stake edge refuses a currency it cannot represent exactly in its fixed six-decimal wire units.

V5 additionally requires betLimitsOverride.market with operatorId (the authenticated operator UUID), brandId, marketId (lowercase identifiers, 1–64 characters) and country (two uppercase letters). The selected version must have an exact operator/brand/market/currency profile; blocked countries and conflicting math-family scope refuse. This country is supplied by the authenticated launcher, not inferred from the browser or an IP-geolocation service. Other override fields still only tighten limits. Legacy/V1–V4 reject a market scope.

The profile pins features.autoplay, features.turbo and features.minimumSpinMilliseconds. Native V1/V2 and Stake play accept optional playOptions: { autoplay: boolean, turbo: boolean } (both required when present, no extra properties). Enabled options require V5 authority and become part of canonical retry identity; omitted options mean manual/normal play. This is declared-mode enforcement, not detection of undeclared client automation. Minimum-spin admission is database-clock-based across sessions for one account and game. Denial precedes RNG/provider dispatch. Stake configuration displays the pinned feature restrictions; native authentication/replay exposes market policy. Disabling the module refuses fresh play while accepted retries and cold recovery retain original currency/FX, limits, market and canonical-request pins.

Responsible-gaming limits

Set account limits — PUT /operator/v1/responsible-gaming/limits (responsible-gaming)

Body is exact and requires every field: playerId (1–256), currency, realityCheckIntervalSeconds (integer 60–86,400 or null), maxSingleWager, dailyNetLossLimit, and dailyDepositLimit (each positive safe integer or null), and maxSessionSeconds (integer 60–86,400 or null). null clears that limit. The response has the five values in force, plus these fields: - selfExcludedUntil and timeOutUntil (ISO timestamps or null); - playBlockedUntil: the later of the two, when play is allowed again on every account of the player; - pending: null, or {"limits": {…}, "effectiveAt": "<ISO>"}.

Raising or removing a limit takes effect 24 hours later, and until then it shows in pending. Lowering a limit applies at once and cancels a pending raise of the same limit. Setting limits never clears or shortens a block. A missing account is 404 {"error":"RESPONSIBLE_GAMING_ACCOUNT_NOT_FOUND"}.

Time out a player — POST /operator/v1/responsible-gaming/time-out (responsible-gaming)

The body is exact: playerId (1–256) and period, one of 24h, 7d, 30d or 42d; any other period is 400 {"error":"INVALID_REQUEST"}. - Effect: the time-out blocks every account of the player, including accounts opened later, and ends their sessions. It never shortens a longer block or a self-exclusion. - Audit: it is recorded in the operator audit log under the calling key. - Response: the limits object above. - Unknown player: 404 {"error":"RESPONSIBLE_GAMING_ACCOUNT_NOT_FOUND"}.

Custodial accounts and transactions

These endpoints are registered only with the custodial wallet dependency. Create an account before posting a transaction. Custodial transaction externalTransactionId is the idempotency identity within the operator, not an HTTP header.

Provision account — POST /operator/v1/accounts (wallet)

Exact body: playerId (1–256) and currency. Success is 201 for a new account and 200 when the same operator/player/currency account already exists. Both return {id, created, balance, currency}. Provisioning is idempotent for that tuple.

Post transaction — POST /operator/v1/wallet/transactions (wallet)

Exact body: playerId (1–256), externalTransactionId (1–256), kind (deposit or withdrawal), positive safe-integer amount, and currency. The account must exist or the response is 404 WALLET_RESOURCE_NOT_FOUND. A completed retry with the same operator, transaction ID, account, kind, amount, and currency returns the original 200 result. Reusing the ID with any different identity, retrying a non-pending/non-completed record, self-excluded deposit, or deposit exceeding a configured daily deposit limit returns 409 WALLET_TRANSACTION_CONFLICT. Insufficient withdrawal funds is 422 INSUFFICIENT_FUNDS. Success is always 200, {id, externalTransactionId, kind, amount, currency, status, balance}; status is normally completed, and balance may be null only if a stored transaction has no balance-after value.

Look up transaction — GET /operator/v1/wallet/transactions/{externalTransactionId} (wallet)

The required path value is 1–256 characters and is tenant scoped. It returns the same transaction shape on 200; missing/foreign IDs return 404 WALLET_RESOURCE_NOT_FOUND.

{"playerId":"player-042","externalTransactionId":"dep-20260921-00042","kind":"deposit","amount":2500,"currency":"EUR"}

{"id":"22222222-2222-4222-8222-222222222222","externalTransactionId":"dep-20260921-00042","kind":"deposit","amount":2500,"currency":"EUR","status":"completed","balance":2500}

Custodial reconciliation

Current scan — GET /operator/v1/reconciliation (reconciliation)

Returns {clean, accounts, mismatches}. accounts is the number of the operator’s accounts. mismatches is an array of runtime query objects with accountId, playerId, currency, storedBalance, and ledgerBalance; the PostgreSQL query returns storedBalance and ledgerBalance as strings, despite other custodial money responses using numbers. This is the current external shape and must not be normalized by clients.

Create run — POST /operator/v1/reconciliation/runs (reconciliation)

Accepts only an empty body (or no body). Success 201 returns a full reconciliation run. A successful run is completed; it snapshots every stored-vs-ledger mismatch into cases. The service may persist a failed run internally when an execution failure occurs, but the HTTP call propagates the failure rather than returning that failed record.

Get run — GET /operator/v1/reconciliation/runs/{runId} (reconciliation)

runId is required UUID. Returns the same full run on 200; missing/foreign runs return 404 WALLET_RESOURCE_NOT_FOUND.

A run is {id,status,accountsChecked,mismatchCount,createdAt,completedAt,cases}. Each case is {id,accountId,playerId,currency,storedBalance,ledgerBalance,delta,status,reasonCode,resolutionNote,ledgerEntryId}. completedAt, reasonCode, resolutionNote, and ledgerEntryId are nullable. Current persisted run statuses are running, completed, failed; normal completed-run case statuses are open, pending_resolution, or resolved.

Request a resolution — POST /operator/v1/reconciliation/cases/{caseId}/resolution-requests (reconciliation)

caseId is UUID. Exact body requires reasonCode (legacy_opening_balance, operator_wallet_confirmed, or data_repair) and note (10–2,048 characters, no NUL; the same rule holds for the reopen and drawn-review notes). Returns the updated case on 200. The first call transitions an open case to pending_resolution; an exact retry by the same requesting key with the same reason and note returns that pending case. Missing/foreign cases return 404 WALLET_RESOURCE_NOT_FOUND; a different retry or unsuitable state is 409 RECONCILIATION_CONFLICT.

Approve a resolution — POST /operator/v1/reconciliation/cases/{caseId}/approve (reconciliation)

caseId is UUID; body must be empty/omitted. Returns the resolved case on 200, creating a reconciliation ledger entry. The approver must be a different API key from the requesting key; the stored/ledger snapshot must still match. A repeat by the same key that already resolved it returns the case. Missing/foreign cases are 404 WALLET_RESOURCE_NOT_FOUND; self approval, stale snapshot, an already-balanced case, or another invalid state is 409 RECONCILIATION_CONFLICT.

Campaigns and grants

Create campaign — POST /operator/v1/campaigns (campaigns)

Requires code and gameCode matching ^[a-z0-9][a-z0-9_-]{1,63}$, currency, positive safe-integer budget, and ISO startsAt/endsAt timestamps. Unknown body properties are 400 INVALID_REQUEST. The game must be active or the response is 422 CAMPAIGN_UNAVAILABLE. The API does not impose an ordering check between startsAt and endsAt beyond database constraints. Success 201 returns only {id}.

Grant campaign funds — POST /operator/v1/campaigns/{campaignId}/grants (campaigns)

campaignId is UUID. Requires playerId (1–256, no NUL), positive safe-integer amount, and idempotencyKey (1–256, no NUL); unknown properties are 400 INVALID_REQUEST. A grant is accepted only for an active, currently in-window campaign, within remaining budget, to an existing account in the campaign currency. Any of those failures, including a same key with a different amount, is 422 CAMPAIGN_UNAVAILABLE. A new grant is 201; an equivalent idempotent retry is 200. Both return {created, balance, grantId}.

Set campaign status — PUT /operator/v1/campaigns/{campaignId}/status (campaigns)

campaignId is UUID. Exact body {status} where status is active, paused, or ended. Valid transitions are active→paused, paused→active while endsAt is still future, and active/paused→ended. Success 200 returns {id,status}. A missing/foreign campaign, no-op, expired resume, or invalid transition is 422 CAMPAIGN_UNAVAILABLE.

Two-person changes

Free-round campaigns, budget campaigns, tournaments, jackpot pools and memberships, the operator's wallet configuration, new API keys and game offers can need two people (MASTER-PLAN H2).

• When: the operator has module two-person-changes on. It is an option, off by default, that the RGS operator sets per operator; no profile forces it, so one person can run an RGS alone (MASTER-PLAN decisions, 2026-10-25).
• One-key routes refuse. These return 409 {"error":"TWO_PERSON_REQUIRED","action":"<action>"} before reading the body, and change nothing:
• POST /operator/v1/free-rounds (free-rounds.create) and POST /operator/v1/free-rounds/{campaignId}/remove (free-rounds.remove);
• POST /operator/v1/engagement/tournaments (tournament.create) and POST /operator/v1/engagement/tournaments/{id}/close (tournament.close);
• POST /operator/v1/jackpots (jackpot.create);
• POST /operator/v1/campaigns (campaign.create) and PUT /operator/v1/campaigns/{campaignId}/status (campaign.status);
• POST /operator/v1/jackpots/{poolId}/memberships (jackpot.membership.offer) and POST /operator/v1/jackpots/{poolId}/memberships/{offerId}/accept (jackpot.membership.accept);
• POST /operator/v1/wallet/signing-keys (wallet.signing-key), PUT /operator/v1/external-wallet/mode (wallet.mode) and PUT /operator/v1/external-wallet/connector (wallet.connector) (Wallet API);
• POST /operator/v1/api-keys (api-key.create);
• PUT /operator/v1/games/{gameCode} with enabled: true (game.entitlement); this one reads the body first, because turning a game off (enabled: false) stays one key;
• POST /operator/v1/external-wallet/operations with kind debit, credit or cancel (wallet.operation, migration 250); a balance query stays one key.
• One key still does: grants to players (they spend a campaign that two people approved), revoking an API key or a signing key (so a leaked key goes at once), and turning a game off.

The same change goes through a request and a second person's decision. These routes work whether or not two people are required, and they are the console's LiveOps requests and decisions (Back office, Two-person changes):

• POST /operator/v1/changes: {action, terms, ttlSeconds}. Returns 201 {id, termsSha256, expiresAt}.
• The key needs the action's scope: wallet for wallet.adjust, wallet-admin for the other wallet.* actions, keys for api-key.create, games for game.entitlement, campaigns for the rest.
• action is one of the fifteen above, market.profile, wallet.adjust, player.erase (scope *, backoffice.md) or round.void (scope reconciliation: the two-person void of a round held in manual review that no other path closes, backoffice.md, "Void a held round"; the approver types the round id back as echo.target). Console user changes (console.user.*) are made in the console only, and this route refuses them (403).
• wallet.adjust (migration 259) corrects a custodial balance (a goodwill credit, an error correction). It has no one-key route: it always takes two people, with no threshold.
  • terms are {externalPlayerId, currency, amountMinor, reason, reference}. amountMinor is a signed, non-zero whole number of minor units as a string ("-250", "125"), within ±(2^53 − 1). reason (1 to 200 characters) and reference (1 to 64) carry no control or direction characters.
  • The proposal is refused (400) unless the operator is active and custodial and the player has an account in that currency with it.
  • Approval posts exactly one ledger entry in the decision's transaction: a credit or a debit of the amount, idempotency key wallet-adjust:{changeId}, with metadata {source: 'backoffice-adjustment', changeId, reason, reference}. It also writes one backoffice.wallet.adjust audit event. result is {changeId, accountId, ledgerEntryId, currency, amountMinor, balanceBefore, balanceAfter}, with exact strings.
  • The approval is refused with 409, and the request stays pending, in four cases: the balance would go negative; the operator is no longer custodial or active; the account is stopped; or a money operation holds the account.
  • The back office lists the adjustments in the player's profile (adjustments, latest 20) and activity (in the window), with the change id and reason.
• terms for wallet.operation are the operations route's body without balance: {operationId, kind, playerId, currency, amount} for a debit or credit, {operationId, kind: 'cancel', playerId, currency, originalOperationId} for a cancel, on an operationId the operator has not used.
• terms for game.entitlement are {gameCode, enabled, currencies}; for the memberships, {poolId, operatorId, gameVersionId} and {poolId, offerId}.
• terms are the same as the one-key route's body, or {campaignId} / {tournamentId} / {campaignId, status}.
• ttlSeconds is 60 to 86,400 (default 3,600).
• POST /operator/v1/changes/{changeId}/decision: {decision, confirm, echo}, where decision is approved or rejected and confirm is the request's termsSha256. The key needs the action's scope. Approval runs the change in the same transaction under the approver's key and returns {decision, result}.
• echo (MASTER-PLAN H2) is what the approving person typed back, read from the change rather than copied by the client. Approving a change that moves money needs {amountMinor, currency}: wallet.adjust its signed amountMinor as a string, wallet.operation a debit's or credit's amount as a string (a cancel needs {currency, target}, the target being originalOperationId). Approving one that cannot be undone needs {target}, the code its subject shows (else its id): free-rounds.remove, tournament.close and campaign.status to ended. Currencies and targets compare in any letter case, amounts exactly. Other changes and rejections need none.
• For api-key.create the terms' label follows the one-key route's rule (at most 128 characters, no NUL; 400 otherwise). The approver issues the key, so they must hold every scope it gets (409 otherwise). result is {keyId, token, expiresAt}: the token is shown only in this answer and never stored with the change.
• wallet.operation calls the operator's wallet, which no transaction can hold.
  • The decision's transaction first checks for an active connector with a valid response key and, for a cancel, an approved debit of that player outside any round. If a check fails, the answer is 409 and the request stays pending.
  • Once the decision commits, the operation is sent once under the approver's key, as the one-key route does. result is that route's answer, and delivery follows the operation's own lifecycle (an unknown result goes to a signed lookup, then manual review; never a blind resend).
  • If the send is refused before it reaches the wallet, result is {operationId, sent: false, error}. No money moved, and the maker proposes again.
• GET /operator/v1/changes[?scope=campaigns|wallet|wallet-admin|keys|games] (that scope, default campaigns): pending requests and the latest decisions of that scope's actions, newest first.
• The console's LiveOps page offers only the campaigns actions; the others are made here.

Who can propose and approve. A key bound to an enrolled person. The platform owner binds keys to people (migration 113); the running RGS cannot. - The maker and the approver must be different people, and the maker must still be enrolled when the decision is made. - Refusals are CHANGE_REFUSED with a message: - 403: the key is not bound to an enrolled person, lacks the action's scope, or the approver made the change; - 404: unknown change; - 409: already decided, expired, wrong confirm, the maker no longer enrolled, or the module refuses the change now; - 400: invalid terms, or an approval whose echo is missing or does not match the change (nothing is recorded, and the request stays pending).

Every route's class (one key, two people, maker-checker step, or still one person) is listed in test/unit/route-classification.test.ts, which fails when a route is added without one.

Dispute evidence for external wallet operations

GET /operator/v1/disputes/wallet-operations/{operationId} (disputes) is tenant-scoped evidence lookup for an external-wallet operation record. It is included here because it is an operator route; configuration and execution of external-wallet operations are documented separately. operationId is UUID and is canonicalized to lowercase before lookup. Missing and foreign IDs intentionally both return 404 {"error":"NOT_FOUND"}.

Optional query parameters are strict: collection is one of callbacks, conflicts, reconciliation, audit, actionAudit; limit is an integer 1–100 (default 50); cursor is a canonical base64url cursor and requires collection. Invalid query/cursor is 400 INVALID_DISPUTE_CURSOR. A coherent response is 200 with {operation,terminalEvidence,roundLink,counts,integrity:{status:"coherent"},collection}. collection is null unless requested. Its page has {name,items,nextCursor,truncatedByBytes}. Pages are capped at 8 MiB; each item is capped at 3 MiB; the core is capped at 4 MiB. Oversize core/item returns respectively 409 DISPUTE_EVIDENCE_TOO_LARGE or 409 DISPUTE_EVIDENCE_ITEM_TOO_LARGE. Any ownership, linkage, or audit-snapshot inconsistency returns 409 DISPUTE_EVIDENCE_INTEGRITY_MISMATCH without leaking foreign identifiers.

The persisted operation.request, terminal response, callback payload, conflict response, audit actor/snapshots, and action-audit metadata are arbitrary JSON objects from their stored records and remain intentionally unconstrained. rawBodyBase64 is standard base64 text. The fragment fully types the stable envelope and each known collection item shape.

Source identity: ed208c392fd33d563ed095cd5ffe95f474abda21 (bubblebeam11, 2026-09-21). This chapter covers 17 paths / 17 operations: every /operator/v1/* route current at that source except /operator/v1/wallet/signing-keys* and /operator/v1/external-wallet*. The RGS now serves 97 /operator/v1/* operations; the endpoint index lists every one. Re-checked against the routes on 5 November 2026 (w21, 78cf205a).

Signed RNG draw-log export (R10)

GET /operator/v1/rng/draw-log?from=<ISO timestamp>&to=<ISO timestamp> requires a reports-scope operator key. The key determines ownership; callers cannot supply an operator ID. The half-open window uses draw creation time, with up to six fractional digits. The streaming NDJSON contains every financially attributed draw visible in the request's snapshot, including explicit unsigned and invalid records. It never exports a server seed.

Save the entire response and verify it offline with node --import tsx tools/verify-rng-draw-log.ts draws.ndjson trusted-roots.json. Provision the public root map independently. The final signature authenticates the header, every ordered record and the count; HTTP 200 without a valid footer is incomplete. Exit 0 means all draws verify, 2 means unsigned history only, and 1 means an invalid file or draw. A valid empty window is signed too. Split windows that exceed the ten-minute export deadline; one export per process is admitted.

See the file format and trust boundary, the operation contract, and the complete endpoint index. This addition is separate from the older chapter source identity above.

Wallet mode approvals require echo.target to match the mode. Connector approvals require the exact case-sensitive endpoint URL in echo.target. See the wallet chapter for direct PUT bodies and scope migration.

Signed external-wallet API (current transport)

M0 implementation delta: History cursors, private interactive replay, live multiplayer entitlements, safe RG limits and request-time wallet destination policy supersede the affected behavior below. The generated reference (openapi.json, index.html and the PDF) is regenerated from the code (MAINTAINING.md).

This document describes the custom signed-wallet transport wired in 232rgs at source commit ed208c392fd33d563ed095cd5ffe95f474abda21, re-checked against the routes on 5 November 2026 (w21, 78cf205a). The BetSymphony transport module is dormant, not an active 232rgs API. packages/adapters/betsymphony/src/betsymphony-transport.ts is therefore not used by this connector; do not use the repository's root openapi.json or BetSymphony routes for this connector.

Boundary and route ownership

The callback has no wildcard CORS. The RGS operator routes require an Authorization: Bearer <operator token> possessing the wallet-admin scope. The callback instead uses the registered Ed25519 public key. The outbound RGS signing private key is separately configured by RGS_WALLET_SIGNING_KEY_ID and RGS_WALLET_SIGNING_PRIVATE_KEY_FILE; if either is absent, the outbound connector routes are not registered.

RGS-hosted paths

There are 8 path items / 8 operations in the inbound fragment:

1. POST /wallet/v1/callbacks/{operatorCode} — signed finalization or balance statement callback.
2. POST /operator/v1/wallet/signing-keys — register an operator Ed25519 public key.
3. DELETE /operator/v1/wallet/signing-keys/{keyId} — revoke an unbound active key.
4. GET /operator/v1/external-wallet/reconciliation/runs/{runId} — retrieve a reconciliation run generated by a balance statement.
5. PUT /operator/v1/external-wallet/mode — select custodial or external settlement.
6. PUT /operator/v1/external-wallet/connector — set the operator endpoint and expected response signing key.
7. POST /operator/v1/external-wallet/operations — submit one durable external-wallet command through RGS.
8. GET /operator/v1/external-wallet/operations/{operationId} — retrieve a stored external-wallet command result.

openapi.json includes their formal schemas, assembled from fragments/wallet.json. This chapter does not cover the unrelated RGS /operator/v1/wallet/transactions or browser /wallet/* APIs.

Two people (MASTER-PLAN H2, migration 247). Registering a signing key (2), the mode (5) and the connector (6) change where the operator's money calls go and which answers are trusted. Where two people are required (module two-person-changes, an option the RGS operator sets per operator), those three routes refuse with 409 {"error":"TWO_PERSON_REQUIRED","action":"wallet.signing-key" | "wallet.mode" | "wallet.connector"}. - The same changes then go through POST /operator/v1/changes with the configuration fields (without echo) as terms, and a decision by a different enrolled person (Operator API, Two-person changes). - Both keys need the wallet-admin scope and must be bound to enrolled people. - Approval applies the terms then, under the approver's key, with the same checks as the route. If they cannot apply now (no such active response key, no active connector for external, a validity window that has passed), the approval is refused with 409 CHANGE_REFUSED and the request stays pending. - Revoking a key (3) stays one key, so a leaked key can be revoked at once.

Callback wire protocol

Request

POST /wallet/v1/callbacks/{operatorCode} accepts only Content-Type: application/vnd.23rgs.wallet-callback+json. The Fastify parser preserves the received UTF-8 bytes as a buffer before JSON parsing. The body limit is 64 KiB. The path parameter matches ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$.

Required headers:

The exact signed byte sequence is:

ASCII(X-Wallet-Timestamp) || 0x2e || ASCII(X-Wallet-Message-Id) || 0x2e || exact received request-body bytes

There is no JSON canonicalization, whitespace normalization, newline addition, URL decoding, or reserialization. A callback must sign the bytes sent on the wire. The RGS verifies Ed25519.verify(null, signedBytes, registeredSpkiPublicKey, decodedSignature).

The timestamp must be a safe integer and within ±30 seconds of RGS wall-clock time. The selected active key is additionally checked at the callback timestamp: notBefore <= timestamp < expiresAt; suspended operators and revoked keys fail authentication.

The body is a strict tagged union. These are synthetic valid shape examples; callback timestamps must be fresh when actually sent:

{
  "type": "transaction.finalized",
  "operationId": "11111111-1111-4111-8111-111111111111",
  "externalTransactionId": "synthetic-wallet-transaction-001",
  "status": "approved",
  "amount": 125,
  "currency": "EUR",
  "balance": 9875
}

or

{
  "type": "balance.statement",
  "statementId": "synthetic-statement-001",
  "asOf": "2026-09-21T12:00:00.000Z",
  "balances": [
    { "playerId": "synthetic-player-42", "currency": "EUR", "balance": 9875 }
  ]
}

A statement has 1–10,000 balance rows, no extra fields, no duplicate (playerId, currency) tuple, and asOf must be no more than 300 seconds old and no more than 30 seconds in the future. statementId, externalTransactionId and playerId are 1–256 characters with no NUL (400 INVALID_REQUEST otherwise, since batch fin). Amount is a positive safe integer; balance is non-negative. Transaction status is approved, declined, reversed or manual_review; reversed is persisted as operation status cancelled and is valid only for a cancel operation.

Callback response

A first accepted callback returns 202 and a byte-identical replay (same operator, message ID, signing-key record, and SHA-256 of raw body) returns 200. The response is:

{
  "id": "22222222-2222-4222-8222-222222222222",
  "messageId": "33333333-3333-4333-8333-333333333333",
  "status": "processed",
  "duplicate": false
}

A newly processed callback has status: "processed"; a replay of a callback whose signed evidence was already retained as a conflict can return status: "manual_review" with duplicate: true. reconciliationRunId is omitted rather than null for a transaction callback; it is preserved on an exact statement replay. A reused message ID with another signing key or different raw-body hash returns 409 WALLET_CALLBACK_CONFLICT.

For a finalization, RGS requires the operation and currency to match, then validates the exact amount. debit, credit, and cancel are eligible; a cancel derives its expected amount from the original approved debit. A callback with a matching existing terminal tuple (mapped status, externalTransactionId, balance, currency) is accepted as separate signed evidence. A different terminal tuple is retained as conflict evidence, changes the operation and callback to manual_review, and returns 409. A remote transaction ID is unique per operator: a second operation claiming it is retained as signed conflict evidence, the losing operation becomes manual_review, and the callback returns 409. The same remote ID may be used by another operator.

Authentication failures (bad media/body framing, inactive key/operator, stale timestamp, invalid signature) return 401 WALLET_CALLBACK_AUTHENTICATION_FAILED; syntactic parse/validation failures return 400 INVALID_REQUEST; unhandled failures return 500 INTERNAL_ERROR.

Outbound operator-hosted wallet protocol

operator-wallet.openapi.json is a standalone OpenAPI 3.1 document with 2 paths / 2 operations. Its server is the required non-routable placeholder https://operator-wallet.example.invalid; replace it operationally by configuring PUT /operator/v1/external-wallet/connector, not by treating the placeholder as a live service.

The connector endpoint must be HTTPS and must not contain username/password. HTTP is accepted only for loopback 127.0.0.1, localhost, or ::1 forms used by local tests. RGS POSTs to the configured endpoint. For recovery it strips query/hash and appends /{operationId} to the configured endpoint path.

Outbound request

For POST /wallet/v1/operations, the strict JSON request is:

{
  "version": 1,
  "operationId": "11111111-1111-4111-8111-111111111111",
  "kind": "debit",
  "playerId": "synthetic-player-42",
  "currency": "EUR",
  "amount": 125
}

amount is required and positive only for debit/credit; it is absent for cancel/balance. originalOperationId is required only for cancel, and absent otherwise. A cancel must reference an approved matching non-round debit; game outcomes cannot be cancelled by this route. The body has no extra keys.

Required request headers are Content-Type: application/vnd.23rgs.wallet-operation+json, X-Rgs-Key-Id, X-Rgs-Timestamp, X-Rgs-Operation-Id, and X-Rgs-Signature. The operation ID in the header equals the body field; the timestamp appears only in the header/signature prefix. RGS signs:

ASCII(X-Rgs-Timestamp) || 0x2e || ASCII(X-Rgs-Operation-Id) || 0x2e || exact outbound JSON bytes

For GET /wallet/v1/operations/{operationId}, RGS sends Accept: application/vnd.23rgs.wallet-operation+json and the same four X-Rgs-* signature headers, but signs only ASCII(timestamp) || '.' || ASCII(operationId) || '.'; there is no request body.

Signed operator response

Both operator endpoints must return HTTP 200 with a content type starting with application/vnd.23rgs.wallet-operation+json, strict JSON body, and:

RGS verifies the response with the public key registered under responseKeyId over:

ASCII(X-Wallet-Timestamp) || 0x2e || ASCII(X-Wallet-Operation-Id) || 0x2e || exact response-body bytes

The strict response body is:

{
  "operationId": "11111111-1111-4111-8111-111111111111",
  "status": "approved",
  "remoteTransactionId": "synthetic-wallet-transaction-001",
  "currency": "EUR",
  "balance": 9875
}

Response status is approved or declined; remoteTransactionId is 1–256 characters. Currency and operation ID must match the request; balance is a non-negative safe integer. No response fields may be added. The response limit is 256 KiB by default.

Durability, duplicate, unknown, and manual review

RGS stores the outgoing request before its first network attempt. Repeating the same operationId with byte-identical derived request returns the stored result with duplicate: true and does not retransmit; a different request using that ID returns 409 EXTERNAL_WALLET_CONFLICT.

A valid direct response makes the stored status approved or declined. A timeout, transport failure, non-200 response, invalid content type, invalid signature/timestamp/identity/body, or oversized response produces a stored unknown result rather than a blind financial retry. By default the RGS runtime outbound deadline is 2,000 ms and the worker recovery client's 5,000 ms; RGS_WALLET_TIMEOUT_MS sets either, from 50 ms up to (not including) the 30,000 ms recovery lease. The service accepts configured deadlines only from 50 through 30,000 ms. A pending operation becomes eligible for lookup recovery after max(60,000 ms, 2 × request timeout); unknown operations are recovered by signed GET, never by re-sending the POST.

Recovery has a 30-second lease by default, up to 10 attempts by default, exponential retry scheduling capped at 300 seconds, and a failed operation becomes manual_review after the configured maximum (permitted range 1–100). A signed terminal response that disagrees with preserved terminal evidence, or a duplicate remote transaction ID within the operator, is retained as evidence and results in manual_review; RGS fails the current caller with 409. manual_review is not a successful approval and has no automatic replacement request. pending is the internal claimed-before-transport state; API callers see the result after the method completes, normally approved, declined, unknown, or conflict.

Signing and verification example

The following Node.js example creates fresh keys at runtime; it has synthetic public identifiers and no fixed private secret. It signs actual bytes and verifies those same bytes.

import { generateKeyPairSync, sign, verify } from 'node:crypto';

const { privateKey, publicKey } = generateKeyPairSync('ed25519');
const timestamp = '1767225600';       // synthetic 10-digit Unix-second test value
const operationId = '11111111-1111-4111-8111-111111111111';
const payload = {
  version: 1,
  operationId,
  kind: 'debit',
  playerId: 'synthetic-player-42',
  currency: 'EUR',
  amount: 125
};
const raw = Buffer.from(JSON.stringify(payload), 'utf8');
const signingBytes = Buffer.concat([
  Buffer.from(`${timestamp}.${operationId}.`, 'ascii'),
  raw
]);
const signature = sign(null, signingBytes, privateKey).toString('base64url');

const headers = {
  'content-type': 'application/vnd.23rgs.wallet-operation+json',
  'x-rgs-key-id': 'synthetic-rgs-key-2026',
  'x-rgs-timestamp': timestamp,
  'x-rgs-operation-id': operationId,
  'x-rgs-signature': signature
};

if (!verify(null, signingBytes, publicKey, Buffer.from(headers['x-rgs-signature'], 'base64url'))) {
  throw new Error('signature did not verify');
}

For a callback, substitute timestamp.messageId. as the ASCII prefix and concatenate the received callback body buffer; for a signed wallet response, substitute responseTimestamp.operationId. and concatenate the exact response buffer.

Key lifecycle

POST /operator/v1/wallet/signing-keys accepts only Ed25519 SPKI PEM public keys. If omitted, notBefore defaults to now minus 30 seconds and expiresAt defaults to 90 days after notBefore. Explicit activation must be between five minutes in the past and seven days in the future. Expiry must be at least five minutes after max(now, notBefore) and no later than 90 days after notBefore. The create response omits notBefore and expiresAt when both were omitted, although the server stores the defaults.

Posting the same active key ID with the same normalized public key and compatible supplied validity is idempotent (200); a different key, status, or supplied validity conflict is 409. Delete marks an active key revoked (204); it is 404 if absent/already revoked and 409 if it is the active response key bound to an active connector. Rotate by register/configure a new active response key first, then remove the old unbound key. The connector update atomically validates that the selected response key is active at configuration time.

Source quirks retained deliberately

• Callback request bodies are signed as bytes but then JSON-decoded as UTF-8; correct JSON with different whitespace is a different signed body and a different replay hash.
• Callback transaction.finalized permits manual_review, while direct operator responses permit only approved or declined.
• A balance.statement compares external rows with latest authoritative terminal-operation evidence, not with the custodial account balance. It produces a completed run and durable cases for balance_mismatch, missing_internal_account, missing_external_balance, or missing_authoritative_evidence.
• Signing-key routes, mode selection and reconciliation GET require operator authentication and the wallet dependency. Connector/operation routes additionally require the externally signed wallet runtime. The mode route is registered without that runtime, but switching to external returns 503 when the runtime or active connector/key is absent.
• POST /operator/v1/external-wallet/operations returns 201 for a newly persisted operation even when its resulting status is unknown; it uses 200 only for an idempotent duplicate.

Cashier/admin separation and typed configuration

The routes in this chapter require wallet-admin; wallet remains cashier-only (accounts, custodial transactions and wallet.adjust). Migration 276 grants existing wallet keys both halves once; newly issued keys receive only their requested scopes. Existing expiry/revocation remains effective.

Direct PUT /operator/v1/external-wallet/mode takes {"mode":"external","echo":{"target":"external"}}. Direct PUT /operator/v1/external-wallet/connector takes {"endpoint":"https://wallet.example/operations","responseKeyId":"wallet-1","echo":{"target":"https://wallet.example/operations"}}. The connector echo is case-sensitive. Missing/wrong echoes return 400. These direct routes still refuse with TWO_PERSON_REQUIRED where enabled; proposal terms omit echo, and the approver supplies it with decision and confirm.

Complete RGS HTTP endpoint index

Source: 3f5afad7d77668ee5b47e72140086514d76b9418. 204 method/path operations: every route the RGS serves with every optional module configured, read from the code (tools/routes.ts) and matched exactly against OpenAPI. /metrics is on the separate metrics listener. Routes that need a module or dependency carry x-registration-condition in the OpenAPI document. PSEI (module P) is proprietary and not listed. Automatic HEAD handling and the five SDK CORS preflights are protocol behavior, not extra business operations. The multiplayer socket and separate showcase routes are described in their chapters.

Complete operation and field reference

This appendix is generated from the two checked OpenAPI 3.1 documents. The preceding chapters explain flows and retry semantics; this appendix lists every operation, parameter, request model, response model and reusable data field. Model names are local to the indicated specification. Required means required within its containing object. A conditional or optional parent does not make that object itself required. Unknown/game-owned JSON is explicitly unconstrained.

Array items use []; union alternatives use oneOf (exactly one), anyOf (one or more) and allOf (all). if / then / else express conditional constraints. A referenced model is defined in the model section for the same specification. Full machine-readable schemas remain authoritative for composition.

RGS-hosted API

Specification: openapi.json · version 2026-11-13+3f5afad.

GET /health/live

Process liveness

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

GET /health/ready

Dependency readiness

Default 2-second deadline. Normal entrypoint checks PostgreSQL, Redis, key/runtime coverage and configured authority readiness.

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

GET /metrics

Prometheus metrics

Served by the separate metrics listener (main.ts: config.metrics host and port), not the API listener.

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Registration: the metrics listener (main.ts).

POST /v1/authenticate

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "launchToken": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

GET /v1/balance

Authentication: SessionBearer.

POST /v1/session/close

Authentication: SessionBearer.

GET /v1/reality-check

Authentication: SessionBearer.

POST /v1/reality-check/acknowledge

Authentication: SessionBearer.

GET /v1/responsible-gaming

Authentication: SessionBearer.

Registration: responsibleGaming dependency is supplied.

POST /v1/responsible-gaming/self-exclude

Authentication: SessionBearer.

Registration: responsibleGaming dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

GET /v1/campaigns

Authentication: SessionBearer.

Registration: campaigns dependency is supplied.

POST /v1/multiplayer/room

Authentication: SessionBearer.

Registration: multiplayerLobby dependency is supplied.

Request body: optional.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{}

POST /v1/play

Authentication: SessionBearer.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "externalRoundId": "round-123",
  "action": "base",
  "wager": {
    "id": "wager-123",
    "amount": 100,
    "currency": "EUR"
  },
  "clientSeed": "example-client-seed"
}

POST /v2/play

Authentication: SessionBearer.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "commandId": "31c8a45d-6294-4bbd-99a2-7a2a4a01c9f1",
  "action": "base",
  "wager": {
    "amount": 100,
    "currency": "EUR"
  },
  "clientSeed": "example-client-seed"
}

POST /v2/recover

Authentication: SessionBearer.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

GET /v1/history

Authentication: SessionBearer.

Registration: rounds dependency is supplied.

GET /v1/rounds/{roundId}/fairness

Authentication: SessionBearer.

Registration: rounds dependency is supplied.

GET /v1/rounds/{roundId}/replay

Authentication: SessionBearer.

Registration: rounds dependency is supplied.

POST /v2/interactive/start

Authentication: SessionBearer.

Registration: interactive runtime dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

POST /v2/interactive/action

Authentication: SessionBearer.

Registration: interactive runtime dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

POST /v2/interactive/recover

Authentication: SessionBearer.

Registration: interactive runtime dependency is supplied.

Request body: required.

Content type: application/json. object; extra fields forbidden

POST /wallet/authenticate

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra field values: Any JSON value

POST /wallet/balance

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra field values: Any JSON value

POST /wallet/play

No caller idempotency or command identifier is accepted; this route creates the round identity.

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra field values: Any JSON value

Illustrative request:

{
  "sessionID": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "amount": 1000000,
  "currency": "EUR",
  "mode": "BASE",
  "gameId": "coin-flip"
}

POST /wallet/end-round

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra field values: Any JSON value

POST /bet/event

Authentication: No header security scheme; use the operation’s body/signature rules where specified.

Registration: rounds dependency is supplied.

Request body: required.

Content type: application/json. object; extra field values: Any JSON value

POST /operator/v1/api-keys

Create an operator API key

Authentication: OperatorBearer.

Operator scope: keys.

Registration: operatorAuth.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "label": "synthetic-ops",
  "scopes": [
    "wallet"
  ],
  "ttlSeconds": 3600
}

DELETE /operator/v1/api-keys/{keyId}

Revoke another operator API key

Authentication: OperatorBearer.

Operator scope: keys.

Registration: operatorAuth.

PUT /operator/v1/games/{gameCode}

Set operator game entitlement

Authentication: OperatorBearer.

Operator scope: games.

Registration: operatorAuth.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "enabled": true,
  "currencies": [
    "EUR"
  ]
}

PUT /operator/v1/responsible-gaming/limits

Set all responsible-gaming limits for an account

Authentication: OperatorBearer.

Operator scope: responsible-gaming.

Registration: operatorAuth && responsibleGaming.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "playerId": "synthetic-player",
  "currency": "EUR",
  "realityCheckIntervalSeconds": 600,
  "maxSingleWager": 500,
  "dailyNetLossLimit": null,
  "dailyDepositLimit": 1000,
  "maxSessionSeconds": null
}

POST /operator/v1/accounts

Provision or find a custodial account

Authentication: OperatorBearer.

Operator scope: wallet.

Registration: operatorAuth && wallet.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "playerId": "synthetic-player",
  "currency": "EUR"
}

POST /operator/v1/wallet/transactions

Post an idempotent custodial deposit or withdrawal

Authentication: OperatorBearer.

Operator scope: wallet.

Registration: operatorAuth && wallet.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "playerId": "synthetic-player",
  "externalTransactionId": "synthetic-deposit-1",
  "kind": "deposit",
  "amount": 2500,
  "currency": "EUR"
}

GET /operator/v1/wallet/transactions/{externalTransactionId}

Look up a custodial transaction

Authentication: OperatorBearer.

Operator scope: wallet.

Registration: operatorAuth && wallet.

GET /operator/v1/reconciliation

Compare stored and ledger balances

Authentication: OperatorBearer.

Operator scope: reconciliation.

Registration: operatorAuth && wallet.

POST /operator/v1/reconciliation/runs

Create a custodial reconciliation run

Authentication: OperatorBearer.

Operator scope: reconciliation.

Registration: operatorAuth && wallet.

Request body: optional.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{}

GET /operator/v1/reconciliation/runs/{runId}

Get a custodial reconciliation run

Authentication: OperatorBearer.

Operator scope: reconciliation.

Registration: operatorAuth && wallet.

POST /operator/v1/reconciliation/cases/{caseId}/resolution-requests

Request reconciliation-case resolution

Authentication: OperatorBearer.

Operator scope: reconciliation.

Registration: operatorAuth && wallet.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "reasonCode": "data_repair",
  "note": "Synthetic verification reconciled this opening balance."
}

POST /operator/v1/reconciliation/cases/{caseId}/approve

Approve reconciliation-case resolution

Authentication: OperatorBearer.

Operator scope: reconciliation.

Registration: operatorAuth && wallet.

Request body: optional.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{}

POST /operator/v1/launch

Issue one-time game launch token

Authentication: OperatorBearer.

Operator scope: launch.

Registration: operatorAuth.

Request body: required. brandId and marketId are sent together or not at all, and playerToken and token are never both sent; either rule broken answers 400 INVALID_REQUEST (app.ts launch: the refine and the handler's own check).

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "playerId": "synthetic-player",
  "currency": "EUR",
  "gameCode": "heist-v2",
  "locale": "en-GB"
}

POST /operator/v1/campaigns

Create a campaign

Authentication: OperatorBearer.

Operator scope: campaigns.

Registration: operatorAuth && campaigns.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "code": "synthetic-bonus",
  "gameCode": "heist-v2",
  "currency": "EUR",
  "budget": 10000,
  "startsAt": "2026-09-21T00:00:00.000Z",
  "endsAt": "2026-09-22T00:00:00.000Z"
}

POST /operator/v1/campaigns/{campaignId}/grants

Grant campaign funds idempotently

Authentication: OperatorBearer.

Operator scope: campaigns.

Registration: operatorAuth && campaigns.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "playerId": "synthetic-player",
  "amount": 500,
  "idempotencyKey": "synthetic-grant-1"
}

PUT /operator/v1/campaigns/{campaignId}/status

Transition campaign status

Authentication: OperatorBearer.

Operator scope: campaigns.

Registration: operatorAuth && campaigns.

Request body: required.

Content type: application/json. object; extra fields forbidden

Illustrative request:

{
  "status": "paused"
}

GET /operator/v1/disputes/wallet-operations/{operationId}

Get tenant-scoped external-wallet operation evidence

Authentication: OperatorBearer.

Operator scope: disputes.

Registration: operatorAuth.

GET /operator/v1/rng/draw-log

Export a signed, ordered RNG draw log

Reports-scope operator export of all financially attributed draws visible in one read-only snapshot, in the half-open created_at window [from,to). The key determines the operator. UTC ordering preserves PostgreSQL microseconds. NDJSON contains one header, indexed public draw records with verified/unsigned/invalid status, and a root-certified signed footer authenticating every preceding byte and the count. No server seed is exported. Save the complete stream and verify offline with tools/verify-rng-draw-log.ts and independently provisioned trusted public roots. HTTP 200 alone does not prove completion: dependency or disconnect failures can truncate the stream. Maximum one export per operator and two per process, 128 rows per page, 15-second idle and 10-minute overall deadlines. Window length is at most 24 hours; to must be at least 30 seconds before the snapshot. Platform draws are not exported. Shared-room receipts may name both consenting operators but contain no player or money details. See docs/design/rng-draw-log.md for the format and trust boundary.

Authentication: OperatorBearer.

Operator scope: reports.

Registration: operatorAuth; export also requires a configured RNG signer and trusted roots.

POST /wallet/v1/callbacks/{operatorCode}

Accept a signed operator wallet callback

Authentication: W_WalletKeyId + W_WalletTimestamp + W_WalletMessageId + W_WalletSignature.

Request body: required.

Content type: application/vnd.23rgs.wallet-callback+json. Model W_CallbackPayload

POST /operator/v1/wallet/signing-keys

Register an operator Ed25519 callback/response key

Authentication: OperatorBearer.

Operator scope: wallet-admin.

Registration: operatorAuth and dependencies.wallet.

Request body: required.

Content type: application/json. object; extra fields forbidden

DELETE /operator/v1/wallet/signing-keys/{keyId}

Revoke an unbound active signing key

Authentication: OperatorBearer.

Operator scope: wallet-admin.

Registration: operatorAuth and dependencies.wallet.

GET /operator/v1/external-wallet/reconciliation/runs/{runId}

Get a reconciliation run created from a signed balance statement

Authentication: OperatorBearer.

Operator scope: wallet-admin.

Registration: operatorAuth and dependencies.wallet.

PUT /operator/v1/external-wallet/mode

Set custodial or signed external settlement mode

Requires wallet-admin and echo.target matching mode.

Authentication: OperatorBearer.

Operator scope: wallet-admin.

Registration: operatorAuth and dependencies.wallet.

Request body: required.

Content type: application/json. object; extra fields forbidden