JRGS Casino API
ReferenceLaunch API

Award a player free rounds

The casino calls POST /free-rounds on the launch API, with a key that holds the free_rounds scope.

POST/free-rounds

Awards one player spins of one game on one market, paid by the casino: each free round is a credit of its win with no debit before it. The player plays them in the next session of the game on that market and in that currency, before any paid round.

Validation, in this order, and the first failure answers: bonusId, player.id and gameId are present; marketId is present; the market exists and belongs to the key's operator; the player's country and currency are the market's; the game is on the market; the game supports free rounds (game_unsupported: the release a new session would run does not declare them); the market allows free rounds in the player's currency (free_rounds_off); bet is one of the market's free rounds bets for the currency; rounds is from 1 to maxRounds; rounds x bet is at most maxTotal for the currency; expiresAt is in the future and at most maxDays days from now. These are the values GET /catalog/games shows in a game's freeRounds, so an award made from them is not refused for its terms.

Free rounds off. A market whose free_rounds feature is not allowed, or that has no bets list, no maxTotal for the currency, or no maxRounds or maxDays, is off: a missing limit is never "no limit".

Wallet. On a real market the casino's current wallet conformance pass must include the free rounds cases, else ERR_WALLET_NOT_CERTIFIED free_rounds. Internal and demo markets are exempt, as for POST /sessions.

The frame is checked once. The market's frame applies when an award is made, never again: a later change neither ends nor alters an award.

Idempotency. bonusId names one award per operator, player and game. Repeating it with the same terms (marketId, player.currency, rounds, bet, expiresAt) answers 200 with the award as it is now, before any other check, so a change of configuration since does not refuse it. The same bonusId with other terms is refused with ERR_VAL bonus_id. An ended award is kept 90 days after it ended; after that its bonusId makes a new award.

Header Parameters

X-Key-Id*string

The id of the signing key, as issued with it.

X-Timestamp*string

Unix seconds, within 60 s of the RGS clock. The first line of the signed payload.

Match^-?[0-9]+$
X-Signature*string

Base64 (standard, padded) Ed25519 signature of "{X-Timestamp}\n{METHOD}\n{path?query}\n{hex(sha256(body))}".

Formatbyte
X-Request-Id?string

Echoed as requestId in an error. One is generated when absent. On POST /sessions the body's requestId replaces it once the body has been read and signed.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Unknown fields are ignored, player.maxStake too.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/free-rounds" \  -H "X-Key-Id: string" \  -H "X-Timestamp: 1793707200" \  -H "X-Signature: string" \  -H "Content-Type: application/json" \  -d '{    "bonusId": "welcome-2026-11",    "marketId": "gb",    "gameId": "slots",    "player": {      "id": "p-1001",      "country": "GB",      "currency": "GBP"    },    "rounds": 10,    "bet": 200000,    "expiresAt": "2026-11-20T00:00:00Z"  }'
{  "bonusId": "string",  "awardId": "3f696bdd-e4bc-4a03-b01a-16da5c324b35",  "marketId": "string",  "gameId": "string",  "player": {    "id": "string",    "currency": "string"  },  "rounds": 0,  "bet": 0,  "expiresAt": "2019-08-24T14:15:22Z",  "state": "active",  "played": 0,  "remaining": 0,  "totalWin": 0}