Free rounds
Awarding a player free rounds: the endpoints, the limits a market sets, how the rounds are played, and what reaches your wallet.
A free round is a spin the casino pays for. You award a player a number of rounds of one game at one stake; the player plays them first, in the next session of that game, and what they win is credited to your wallet. Nothing is debited for a free round.
Free rounds are on for the game, the market and the currency only where the
catalog says so (see The frame). Today only slots supports
them.
Lifecycle
An award is in one state:
| State | Meaning |
|---|---|
active | Rounds are left and expiresAt has not passed. |
completed | Every round was played. |
expired | expiresAt passed with rounds left. Those are not played. |
cancelled | You cancelled it. Rounds left are not played. |
An award is active, then ends in exactly one of the other three. Its terms
(rounds, bet, expiresAt) never change after it is made.
The routes need a key with the free_rounds scope, a scope of its own that you
grant a key deliberately. A key without it is refused as for any missing scope
(see Authentication). Requests are signed as the other
launch routes are, and amounts are integer micro-units: 1000000 is 1.00.
The four endpoints
Award: POST /free-rounds
POST /free-rounds HTTP/1.1
Host: rgs.example.com
Content-Type: application/json
X-Key-Id: casino-1
X-Timestamp: 1793700000
X-Signature: <base64 Ed25519 signature>
{"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": "welcome-2026-11",
"awardId": "019a4b5e-6f70-7c3d-8e9f-0a1b2c3d4e5f",
"marketId": "gb",
"gameId": "slots",
"player": { "id": "p-1001", "currency": "GBP" },
"rounds": 10,
"bet": 200000,
"expiresAt": "2026-11-20T00:00:00Z",
"state": "active",
"played": 0,
"remaining": 10,
"totalWin": 0
}The answer is 201 when the award is new and 200 when bonusId already made
this award: the repeat answers 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 (marketId, player.currency, rounds, bet, expiresAt) is
refused with ERR_VAL, reason bonus_id.
bonusId is your own id, unique per casino, player and game. The RGS gives the
award its own awardId, which a free round's credit carries.
Read: GET /free-rounds/{bonusId}?playerId=p-1001&gameId=slots
{
"bonusId": "welcome-2026-11",
"awardId": "019a4b5e-6f70-7c3d-8e9f-0a1b2c3d4e5f",
"marketId": "gb",
"gameId": "slots",
"player": { "id": "p-1001", "currency": "GBP" },
"rounds": 10,
"bet": 200000,
"expiresAt": "2026-11-20T00:00:00Z",
"state": "active",
"played": 4,
"remaining": 6,
"totalWin": 750000
}played and totalWin follow the rounds played, remaining is 0 once the
award has ended. An unknown award is 404, ERR_VAL, reason not_found.
This is also where you learn of an expiry or a cancel: see
How the end shows in the wallet.
Cancel: DELETE /free-rounds/{bonusId}?playerId=p-1001&gameId=slots
Ends an active award as cancelled; the answer is the award. A spin already
started finishes, and it counts, so played may be one higher than when you
sent the cancel. Rarely, that spin is then undone, when the RGS fails before it
pays: played still counts it, but no credit comes for it. Your credits, each
marked with the award, are the authority on the rounds played. An award that
has already ended is answered as it is, so a repeat is safe. An unknown award is
404, reason not_found.
List: GET /players/{playerId}/free-rounds?gameId=slots
{ "items": [ { "bonusId": "welcome-2026-11", "state": "active", "played": 4, "remaining": 6, "…": "…" } ] }The player's awards in the game, active first, then the newest first, each as
in the read above. gameId is required.
A missing playerId or gameId on read, cancel and list is ERR_VAL with an
empty reason. Every field is listed in the API reference.
The frame
The RGS team sets what an award may be, per market, not per casino: the allowed
bets for each currency, the most rounds in one award, the largest
rounds × bet for each currency, and the longest validity in days. You see it
in the catalog, in freeRounds on each game of
GET /catalog/games where the market
allows free rounds and the game's release supports them:
"freeRounds": {
"bets": { "GBP": [100000, 200000, 500000] },
"maxRounds": 50,
"maxTotal": { "GBP": 25000000 },
"maxDays": 30
}The catalog lists only currencies that have both a bets list and a maxTotal.
A game without freeRounds cannot be awarded on that market. An award made
from these values is not refused for its terms. The frame applies once, when the
award is made: a later change neither ends nor alters an award.
The frame fails closed. A market with free rounds not allowed, with no bets list
or no maxTotal for the currency, with no maxRounds or no maxDays, or with
a limit of 0, is off: a missing limit is never "no limit".
Refusals
All are 400; none makes an award. The checks run in this order and the first
failure answers.
Error, details.reason | Cause |
|---|---|
ERR_VAL, empty | bonusId, player.id or gameId is missing. |
ERR_VAL body | The body is unreadable, over 1 MiB or not JSON. |
ERR_VAL market, ERR_ATE market, ERR_LOC country, ERR_VAL currency, ERR_VAL game | As for POST /sessions: the market is missing, unknown or not yours, the player's country or currency is not the market's, or the game is not on it. |
ERR_VAL game_unsupported | The release a new session would run does not support free rounds. |
ERR_VAL free_rounds_off | The market has free rounds off, or no complete frame, in the player's currency. |
ERR_VAL bet | bet is not one of the market's free rounds bets for the currency. |
ERR_VAL rounds | rounds is 0 or above maxRounds. |
ERR_VAL total | rounds × bet is above maxTotal for the currency. |
ERR_VAL expires_at | expiresAt is absent, in the past, or more than maxDays days from now. |
ERR_WALLET_NOT_CERTIFIED free_rounds | Your wallet has not passed the free rounds conformance group. |
ERR_VAL bonus_id | The bonusId already made an award with other terms. |
None of them is retryable: change the request, or wait for the configuration
it names to change. A 500 is ours and is always retryable; repeating the same
bonusId is safe.
How the rounds are played
- Forced play. In a session on the award's market and in its currency, opened
at or after the award's creation, the player plays the award before any paid
round, at the award's bet. The bet cannot be changed meanwhile. The launch
answer carries
freeRounds {bonusId, remaining}so you can see it, and a repeat or a new launch URL answers the same. It may be absent when the RGS could not tell at launch: the session still opens and plays the award. - An award made mid-session does not interrupt it. Paid play goes on, and
the award is played from the next launch, a new
POST /sessions. A new launch URL for the same session keeps it as it was. - Only where the game supports it. An award is forced in a session whose game version offers free rounds. The market's switch only stops new awards: existing awards still play after a market turns free rounds off.
- Several awards for one game are played oldest-expiring first.
- No player limits. The award's bet is not checked against the player's
maxStakeor the market's stake limit, because none of the player's own money is staked. - No jackpots. Free rounds neither feed nor win jackpots.
Ends
- Completed. The spin that uses the last round closes the award.
- Expired. From
expiresAtno new spin starts; a spin already started finishes. An expiry is noticed within a minute ofexpiresAt. - Cancelled. A spin already started finishes, and it counts.
What reaches your wallet
A free round is a credit with no debit. Its credit is the ordinary
{roundId}:credit and carries a freeRounds object, which is how you tell a
free round:
{
"transactionId": "0193a5c2-7a1e-7c3b-9f00-2b1d4e6a8c10:credit",
"roundId": "0193a5c2-7a1e-7c3b-9f00-2b1d4e6a8c10",
"playerId": "p-1001",
"gameId": "slots",
"gameVersion": "1.4.0",
"variant": "965",
"currency": "GBP",
"amount": 450000,
"freeRounds": {
"bonusId": "welcome-2026-11",
"awardId": "019a4b5e-6f70-7c3d-8e9f-0a1b2c3d4e5f",
"index": 3,
"rounds": 10,
"bet": 200000
}
}| Field | Meaning |
|---|---|
bonusId | Your id of the award. |
awardId | The RGS's id of the award. |
index | The round's place in the award, from 1. |
rounds | The award's total number of rounds. |
bet | The nominal stake of each round, in micro-units. |
Accept it like any credit: it moves the balance by
amount once, a repeat answers ok with alreadyProcessed: true, and a win of
0 is credited too. Your wallet needs to expect a credit with no debit before
it, and not to refuse it for that.
How the end shows in the wallet
There is no wallet call for the end of an award.
- Completed. The award is used up when a credit's
freeRounds.indexequalsfreeRounds.rounds. The player is back on paid play when the next round comes with a debit and nofreeRounds. - Expired or cancelled. Nothing is sent. Read the award with
GET /free-rounds/{bonusId}: itsstate,playedandtotalWinsay how it ended. A spin in flight when it ended still credits, so the last credit you see may have anindexbelowrounds.
Reusing a bonusId
An ended award is kept for 90 days after it ended. In that time its bonusId
answers the award (a repeat of the same terms is 200; other terms are
bonus_id) and GET finds it. After 90 days the award is dropped: GET is
404, it is not listed, and the same bonusId makes a new award.
Reconciliation and conformance
A free round is a credit with no debit, and that is how it is listed in your
POST /operations export and compared; see
Retries, idempotency and reconciliation.
Your wallet must pass an optional group of the
conformance suite, "a free round
credit with no debit", before you can award on a real market. Demo and internal
markets are exempt. Without the pass, POST /free-rounds is refused with
ERR_WALLET_NOT_CERTIFIED, reason free_rounds. The suite's version is not
raised, so passing the group changes nothing else.