🎁 Description

Command grantfs – Grant Free Rounds / Feature Spins to a User (Eligible Slot Games Only). Also known as command 29, in API VERSION 1.0.

This command allows you to grant free rounds (freebet) or feature spins (feature_spins) to a specific user in an eligible game. Each granted spin will be played with the defined bet per line and number of lines, optionally applying a win multiplier, win limit, and expiration date.

freebet - FREE ROUNDS. You (the operator) fund N rounds at a fixed bet. The player plays N ordinary base-game rounds of the game at the bet in the grant; the bet is never charged to the player, and the player keeps the wins, credited in one amount when the rounds end. Works on any slot and on the G4T arcade games. Industry name: free rounds / free spins (Pragmatic Play: "Free Spins Bonus").

What the player sees (freebet). A freebet grant is offered the next time the player opens that game: a popup says how many free games they have and what each is worth (EG "You have 2 free games worth EUR5 (EUR1.00 x 5 Lines)") with PLAY NOW and PLAY LATER. After PLAY NOW the game plays at the grant's bet and lines — the bet must be one of the game's bet_sizes values from command 24 (any other value is refused at grant time with Bet value must be positive and within bet values list), so the game can step its bet selector straight to it. Only the spins played after PLAY NOW use the grant: they are not charged, and fsStatus moves from pending to active as they are played and to played when the last one ends and the winnings are credited in one amount. A spin the player makes without accepting the offer is an ordinary bet, and the grant stays pending until it is used or it expires. After expiry_date (Y-m-d, GMT) the offer is no longer shown and fsStatus reads expired.

feature_spins - FEATURE SPINS. An entry into the game's own free-spins feature (its bonus round), granted as a promotion. No bet is charged; the spins play with the feature's own math, at the grant's stake and multiplier (fs_mult, empty = the game's own). The winnings are credited in one amount when the feature ends. Works only on slots that have a free-spins feature. These are NOT free rounds: the player is taken straight into the bonus feature, so give them rarely (for example to VIP players). Industry name: instant bonus / feature trigger (Pragmatic Play: "Instant Bonus").

MAIN SPIN RTP (payout) is usually around 50% = 0.5 x TOTAL BET.
SPECIAL FEATURE RTP is usually around 3000% (three thousands percent) = 30x TOTAL BET.
In some games it increase to 100x TOTAL BET or even 200x TOTAL BET for the SPECIAL FEATURE.

📜 Sample JSON Request (from your server to the RGS-CWS server)
{ "command": "grantfs", "login": "demoaccount", "gameid": "6857", "freespins": 10, "bet": 0.10, "lines": 25, "totalwinlimit": 100.00, "expiry_date": "2026-12-31", "fs_type": "freebet", "apiusername": "your_api_username", "apipass": "your_api_password", "uniqid":"oiahtog12793g5497agwe9751515as5y1" }

Sample request: "fs_type": "freebet" (or "fs_type": "feature_spins").

📥 Input Parameters (from your server to the RGS-CWS server)

Parameter

Mandatory

Description

Type

*command

✅

Must be "grantfs"

string

*login

✅

Username (min. 6 characters). Required unless userid is used. Send the bare login (on the staging environment our replies show it prefixed stg_u<operatorid>_). Provide either login or userid, not both.

string

userid

❌

RGS-CWS user ID. Cannot be used together with login.You must provide either login or userid — not both.

string

*gameid

✅

ID of the eligible game. feature_spins: the game must show "freespins": 1 in command 24. freebet: any active slot or G4T arcade game.

string

*freespins

✅

Number of spins to grant. Must be between 1–1000.

integer

*bet

✅

Bet per line. Must fall within the game's minbet/maxbet, and exist in bet_sizes from command 24.

float

*lines

✅

Number of paylines used. Must not exceed the game's max lines. For fixed-line games, it must match the predefined value.

integer

currency

❌

The currency the player plays the granted rounds in. Accepted forms, all equivalent: the ISO code the player was launched with — EUR, USD, GBP, COINS (any case) — recommended; or the currency sign — €, $, £. When currency is empty, it is read from the player's login (the last _CUR part — the currency the player was launched in), else the platform's default currency. The grant activates only in a session of that currency.

string

*totalwinlimit

✅

Win cap. If > 0, any excess winnings are forfeited after the granted spins. Set 0 for no limit.

float

fs_mult

❌

Override multiplier (e.g. 1 = no boost). Set 0 or omit to use game’s default multiplier.

integer

*expiry_date

✅

Expiration date for the grant. Use format: Y-m-d. After this date, the grant is no longer usable. The date is GMT.

string

unlock_limit

❌

Wagering requirement multiplier (reserved for future use; currently not supported in remote RGS mode).

integer

*fs_type

✅

One of exactly two values: "freebet" or "feature_spins" (explained in the note at the top of this page). Any other value is refused — see the refused-values note under this table.

string

*apiusername

✅

Your API username

string

*apipass

✅

Your API password

string

*uniqid

✅

A unique grant identifier generated by you, one per grant (unique per operator). This makes the call idempotent. Repeating a grantfs with a uniqid that already created a grant: with the SAME request (fs_type, login, gameid, freespins, bet, lines, fs_mult, currency) returns OK Grant already processed (idempotent) and the original freespins_id; nothing new is created. With a DIFFERENT request it returns ERROR uniqid <id> was already used for a different grant (<the differing fields>); send a new uniqid and creates nothing. A replayed feature_spins request can also return ERROR uniqid <id> already granted feature_spins (grant id <N>, <req> spins requested; the round has since grown to <stored> spins by a retrigger); a uniqid grants once and this request grants nothing new - send a new uniqid for a new grant: the same request was replayed after the player's feature retriggered, so the grant now holds more spins than were requested — nothing is granted again, and the reply also carries freespins_id (the existing grant) with status ERROR.

string

You must provide either login or userid — not both.

Any other value for fs_type (including the older vipfs, bonus and freespins, or an empty value) returns:
{"status":"ERROR","message":"Unknown fs_type: send freebet or feature_spins. freebet = FREE ROUNDS (the operator funds N rounds at a fixed bet; the player keeps the wins). feature_spins = an entry into the game's own free-spins feature (no bet is charged; the feature's own math)"} - no grant is made.

Refusals for currency (nothing is created, the uniqid stays free):
ERROR Unknown currency <value>: send the ISO code the player plays in (e.g. EUR, USD, COINS)
ERROR currency <value> is not the currency of player <login>; send the player's own currency or leave currency empty

Other refusals (status ERROR; nothing is created): A unique grant id (uniqid) is required to grant freespins/freebets · uniqid <id> was already used for a grant that no longer exists; send a new uniqid · User/Player does not exist · Game does not support Freebets · Game does not have Freespins Feature · You can only grant between 1 and 1000 freespins · Bet value must be positive and within bet values list: … · Bet value must be within bet limits; Min Bet: …; Max Bet: … · Lines value must be positive and <= than maximum number of paylines · In this game, the selected paylines must be equal to the maximum number of paylines · Total Win Limit must be numeric and >=0. You can set it to 0 to deactivate the limit. · Invalid expiry date - date format incorrect ED1 · Invalid expiry date - date does not exist ED2 · Invalid rollover multiplier. Value must be numeric. EG: 50 if you want the rollover to be x50 · Invalid freespin multiplier. Value must be numeric. · Failed to create the freebet grant / Failed to create the freespins grant.

Replies: Free Rounds granted: N base-game spins at bet X on game G; ... / Feature Spins granted: N spins of the game's own free-spins feature at bet X (multiplier M) on game G; ....

📃 Sample JSON Response (returned by RGS-CWS)

✅ Success:

{ "status": "OK", "message": "Free Rounds granted: 10 base-game spins at bet 0.10 on game 6857; winnings credited in one amount when the rounds end", "freespins_id": 315 }

❌ Failure:

{ "status": "ERROR", "message": "You can only grant between 1 and 1000 freespins" }
📤 Output Parameters (returned by RGS-CWS)

Parameter

Required

Description

Type

*status

✅

"OK" or "ERROR"

string

message

✅

Always returned: on success the grant description (Free Rounds granted: … / Feature Spins granted: …), on ERROR the reason (e.g., validation failure)

string

freespins_id

on OK only

The integer id of the grant; send it back with the same fs_type to cancelfs. Note: This is not the same as the gameplay ID, which is generated after the user starts playing.

integer

✅ Operator Notes

  • Always send a unique uniqid per grant. Retries with the same uniqid are safe — they return the original grant (response message "Grant already processed (idempotent)" with the original freespins_id) and never double-grant. A missing uniqid is rejected.

  • A second request with a uniqid that is still being processed answers {"status":"ERROR","message":"A grant for this uniqid is already being processed"} - send the same request again a moment later.

  • Confirm that the selected bet and lines match the game's supported configuration.

  • After the granted spins are consumed or expired, the user must reopen the game to refresh state.

  • You can apply a win cap (totalwinlimit) or override the win multiplier (fs_mult) if needed.

  • Always use the freespins_id to track session history or troubleshoot.

  • Winnings from a grant are sent via a balance_adj request with type=win, but only after all granted spins have been completed.