03 — the randomness
The RNG
The RNG hands you provably-fair uniform floats in [0,1) — nothing else. No paytable, no house edge, no reels. Your game maps the float to a reel result, so the RTP is your responsibility, and every draw is independently verifiable by the player.
Basics
| Base URL | https://rng.domin8.fun |
| Auth | header X-API-Key: <RNG_API_KEY> — server-side only, from env |
game_model | a stable namespace for your seed/nonce stream — pick one label, e.g. yourslot, and never change it |
/randomThe draw your slot makes for every random decision:
{ "user_id": "tg:123456789", "game_model": "yourslot" }{ "roll": 0.5273940184, "nonce": 8, "server_seed_hash": "…sha256…" }Each call advances the nonce by one. A 5-reel spin = 5 calls, one per reel — that keeps the audit trail transparent. (You may instead expand one roll deterministically in your game, but then document the expansion so a verifier can reproduce every reel.)
Fail safe for the house
/random call fails (non-2xx or timeout), the spin failed — never settle a win from a missing draw. The stake is already locked, so you can retry the spin with the same bet_id or refund it.How a roll is made (verifiable)
roll = HMAC_SHA256(server_seed, "{client_seed}:{nonce}") // top 52 bits
/ 2^52 // → float in [0,1)The server seed is committed by its SHA-256 hash before any spin. After a rotate reveals it, the player can recompute every past roll — and since your reel mapping is deterministic, every past spin.
Seed lifecycle
| Endpoint | What it does |
|---|---|
POST /seed/active | get (or lazily create) the active pair → { pair_id, server_seed_hash, client_seed, nonce } |
POST /seed/client | let the player set their own client seed |
POST /seed/rotate | reveal the old server_seed and start a fresh pair — the verify moment |
To match the platform standard, give players a small fairness panel: current hash, editable client seed, the advancing nonce, and a rotate-and-verify action.