Award a player free rounds
The casino calls POST /free-rounds on the launch API, with a key that holds the free_rounds scope.
/free-roundsAwards 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
The id of the signing key, as issued with it.
Unix seconds, within 60 s of the RGS clock. The first line of the signed payload.
^-?[0-9]+$Base64 (standard, padded) Ed25519 signature of "{X-Timestamp}\n{METHOD}\n{path?query}\n{hex(sha256(body))}".
byteEchoed 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}