Overview
The two halves of a JRGS integration: the launch API you call, and the seamless wallet you implement.
JRGS is a remote game server (RGS). It runs the games, decides every outcome and keeps the round journal. The money stays with you: the RGS never holds a player balance, and every stake and win moves through your wallet.
An integration has two halves, and they go in opposite directions.
| Who calls whom | Signed with | Pages | |
|---|---|---|---|
| Launch API | your platform calls the RGS, to list games and start sessions | your Ed25519 private key | Launching a game |
| Wallet | the RGS calls your wallet, to read balances and move money | a shared HMAC-SHA256 secret, both ways | Wallet |
Both are described on Authentication and signing. Each also has a machine-readable OpenAPI document; see the Reference section in the sidebar.
A round at a glance
- Launch. Your platform calls
POST /sessionsfor a player and a game. The RGS answers with alaunchUrl; you send the player's browser to it. The game client opens the session with the single-use token in that URL. - Debit. When the player places a bet, the RGS calls your
POST /debitwith the stake. A debit your wallet refuses is a bet that is not played. - Outcome. The RGS decides the outcome from the game's certified math and records it in its journal.
- Credit. The RGS calls your
POST /creditwith the win, even when the win is 0, which settles the round. - Rollback. If a debit's outcome is unknown, the RGS does not guess: it calls
POST /rollbackfor that debit, and you return the stake if you took it. Unknown means a timeout or network failure, any non-2xx status other than401or403, an answer the RGS cannot read or whose signature does not hold,DUPLICATE, or an error code that is not on the list.
Credits and rollbacks settle money that is already decided, so the RGS keeps repeating them, with the same
transactionId, until it gets a final answer. Your wallet must therefore be idempotent by transactionId. The
details are on Retries, idempotency and reconciliation, and what each answer
means for the money on Errors and money states.
Amounts
Every amount, in both APIs, is an integer number of micro-units of the currency: 1000000 is 1.00, 200000 is
0.20. There are no decimals and no floating point anywhere in the protocol. A currency is its ISO 4217 code, such as
GBP.
Where to go next
Getting started
The shortest path from keys to a first round.
Authentication and signing
Ed25519 for launch requests, HMAC for wallet calls, with code.
Launching a game
The catalog, POST /sessions and the launch URL.
Wallet
The five calls your wallet answers: balance, debit, credit, rollback, operations.
Errors and money states
Which answers are final, which are unknown, and what happens next.
Retries, idempotency and reconciliation
How the RGS repeats calls and how both ledgers are matched.
Jackpots, history and replay
Jackpot wins, round history and replays.
Environments and limits
Hosts, timeouts, sizes and the latency we require of your wallet.
Conformance and going live
The wallet test suite that must pass before real players can play.