Implementing the wallet

Your wallet is the system of record for player money. The RGS calls four endpoints on it. This page is the contract; the reference wallet is a working implementation to start from.

The three facts

1. The RGS retries until it gets a definitive answer, effectively forever.
2. A replay never moves money twice. Every money movement has an RGS-generated id; use it as your idempotency key.
3. A 2xx is a promise that the money is durably correct. If you are uncertain, answer 5xx.

Endpoints you serve

The base URL is your wallet ingress URL, registered per environment. If you also integrate with another RGS (for example Engine), give RuneCode its own ingress path or host so the right key is used and round ids from two RGSes never collide.

Verifying the call

Every POST carries x-operator (your slug) and x-signature (Base64 Ed25519 over the raw body). Check the slug, verify the signature against both RGS keys (current and standby) before parsing, then parse the same bytes. See Authentication. SDK helper: verifyWalletRequest / verify_wallet_request / VerifyWalletRequest.

Money

Integers only, in micro-units: 1_000_000 is 1.00. The currency on every money object must equal the session currency (ERR_BAD otherwise). For currencies with more than six decimals the RGS also sends amountMinor (a decimal integer string) and scale, which are authoritative when present; wallets that ignore them stay compliant.

Identifiers

POST /v1/balance

{ "token": "9f0c1d2e-…" }   →   { "balance": { "amount": 1000000000, "currency": "USD" } }

Errors: ERR_IS (unknown token), ERR_ATE (bad signature or operator). A pure read.

POST /v1/debit

{ "token": "9f0c1d2e-…", "round": 4119983943, "mode": "BASE", "active": true, "ip": "203.0.113.5",
  "debit":  { "id": "019a1b2c-3d4e-7f60-8a1b-2c3d4e5f6a7b", "amount": 1000000, "currency": "USD" },
  "credit": null }

• active: true keeps the round open; false closes it now (a 0-win close-at-play, or a single-shot round).
• credit is a concurrent settling credit (id, amount, ref = the debit id, currency) or null. The stake alone must be coverable: a concurrent credit never funds its own stake (ERR_IPB).
• Answer: { "debit_id": "…", "credit_id": "…"?, "balance": { … } } (credit_id only when a credit was sent).
• Errors: ERR_IPB (stake not coverable), ERR_BAD (zero or negative amount, currency mismatch, schema, or a fenced debit), ERR_BC (round already closed), ERR_IS.

POST /v1/credit

{ "token": "9f0c1d2e-…", "round": 4119983943, "active": false, "ip": "203.0.113.5",
  "credit": { "id": "019a1b2c-4e5f-7a80-9b1c-2d3e4f5a6b7c", "amount": 2000000, "ref": "019a1b2c-3d4e-7f60-8a1b-2c3d4e5f6a7b", "currency": "USD" } }

• A losing close is "credit": null (never a zero-amount credit).
• The round must have at least one debit (ERR_BNF); a new credit on a closed round is ERR_BC; the token must be the one that opened the round (ERR_IS otherwise, even if the round is later continued from another session).
• Answer: { "credit_id": "…"?, "balance": { … } }.
• A credit is never rolled back and never fenced: a win is owed, and the RGS retries it forever.

POST /v1/rollback

{ "token": "9f0c1d2e-…", "round": 4119983943, "active": false,
  "rollbacks": [ { "id": "019a1b2c-5f60-7b90-8c2d-3e4f5a6b7c8d", "ref": "019a1b2c-3d4e-7f60-8a1b-2c3d4e5f6a7b" } ] }

• Idempotent on the debit ref: two different rollback ids for the same debit refund once.
• Answer: { "rollback_ids": ["…"], "balance": { … } }, in input order.
• Fencing. A rollback whose ref your wallet has never seen answers 200 and refunds nothing, but you must remember it: a debit with that id that arrives later is refused (ERR_BAD). This is what stops a delayed copy of a debit from charging a round the player was told failed.
• A rollback whose ref names a debit you refused answers 200 and refunds nothing.
• ERR_BC if the round was settled by a credit. If the debit is still pending on your side, answer 5xx so the RGS retries.

Errors you answer with

Body: { "code": "<ERR_CODE>", "message": "…" } (note code, unlike the game API).

How the RGS classifies your answer: a 2xx with a valid body is done; a 2xx with an unparseable body is unknown and is retried (your replay returns the stored result); a 4xx with a known code above is terminal; a 4xx with an unknown code, 408, 425 and 429 are retried; any 5xx, timeout, connection or TLS error is retried.

Timing

• The RGS waits 3 seconds per attempt while a player's request is open, then retries in the background with exponential backoff (1 s, 2 s, 4 s, up to 60 s, with jitter) with no maximum number of attempts.
• A debit that has no answer by the game deadline is stopped and replaced by a fencing rollback, retried the same way. Your wallet may therefore see a debit after the rollback for it. Fencing is what makes that safe.
• After 15 minutes of failure we alert; after 24 hours the transaction is parked and we page, but we keep retrying hourly.
• Retries are byte-identical: the same body and the same signature. That makes it easy to prove, from your side, that two requests are the same transaction.
• Sessions do not expire in your wallet. The RGS stops accepting new bets 24 hours after launch (configurable) but still sends debits, credits and rollbacks for rounds that are open.

Health

GET /health is unsigned; any 2xx means healthy. We poll it. Three consecutive failures, or a high share of unknown-outcome debits or slow debits, marks your integration degraded: new plays are paused (the game shows bets paused, launches answer 503 ERR_MAINT) while settlement retries continue. Make /health reflect whether you can really take a debit.

What a real wallet must add

The reference wallet keeps its books in memory, which is fine for learning and for testing your integration, and not for production. A production wallet applies the same rules on durable storage:

• the idempotency record and the money movement commit in the same database transaction, with unique constraints on the ids;
• concurrent debits for one player are serialized (a row lock or a conditional update), so two stakes can never both pass the balance check;
• a refused debit's id is stored as consumed, and answered identically if the same debit arrives again;
• fences are durable;
• a 5xx is the answer to anything you cannot prove committed.

Reference wallet

It passes RuneCode's real wallet conformance kit with verdict pass (examples/reference-wallet/wcs.sh): every row, and every capability flag true (single-shot rounds, close-at-play, remembers refusals). See Testing and going live.

examples/reference-wallet/wallet.ts implements everything above in about 200 dependency-free lines, using the SDK's verification. examples/reference-wallet/e2e.sh runs the real RGS against it:

ok  authenticate: the RGS asked the wallet for the balance (signed /v1/balance) …
ok  7 plays, 2 wins: the RGS sent signed /v1/debit and /v1/credit calls
ok  the wallet's books agree with the RGS: 1000000000 -> 994000000 (expected 994000000) …
ok  a signature from another key is refused (401 ERR_ATE)