JRGS Casino API

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:

StateMeaning
activeRounds are left and expiresAt has not passed.
completedEvery round was played.
expiredexpiresAt passed with rounds left. Those are not played.
cancelledYou 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.reasonCause
ERR_VAL, emptybonusId, player.id or gameId is missing.
ERR_VAL bodyThe body is unreadable, over 1 MiB or not JSON.
ERR_VAL market, ERR_ATE market, ERR_LOC country, ERR_VAL currency, ERR_VAL gameAs 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_unsupportedThe release a new session would run does not support free rounds.
ERR_VAL free_rounds_offThe market has free rounds off, or no complete frame, in the player's currency.
ERR_VAL betbet is not one of the market's free rounds bets for the currency.
ERR_VAL roundsrounds is 0 or above maxRounds.
ERR_VAL totalrounds × bet is above maxTotal for the currency.
ERR_VAL expires_atexpiresAt is absent, in the past, or more than maxDays days from now.
ERR_WALLET_NOT_CERTIFIED free_roundsYour wallet has not passed the free rounds conformance group.
ERR_VAL bonus_idThe 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 maxStake or 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 expiresAt no new spin starts; a spin already started finishes. An expiry is noticed within a minute of expiresAt.
  • 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
  }
}
FieldMeaning
bonusIdYour id of the award.
awardIdThe RGS's id of the award.
indexThe round's place in the award, from 1.
roundsThe award's total number of rounds.
betThe 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.index equals freeRounds.rounds. The player is back on paid play when the next round comes with a debit and no freeRounds.
  • Expired or cancelled. Nothing is sent. Read the award with GET /free-rounds/{bonusId}: its state, played and totalWin say how it ended. A spin in flight when it ended still credits, so the last credit you see may have an index below rounds.

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.

On this page