🎁 Description

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

This command allows you to grant a number of freespins to a specific user in an eligible game. Each freespin will be played with the defined bet per line and number of lines, optionally applying a win multiplier, win limit, and expiration date.

⚠️ Important: For now, freespins are executed in the game’s special feature mode, which may offer RTP > 100%. We plan to support freespins in main mode (low RTP) soon. Until then, use this feature only if you accept the higher payout risk. You can still control the payout by setting a max totalwin or a higher rollover requirement.

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.

If you are concerned, please note that this SPECIAL FEATURE is meant mostly for VIP players.
Players can trigger the SPECIAL FEATURE in the normal game very rarely (once every 200-300 spins) or by using the BUY FEATURE and paying a lot of money.
However, if the player receives SPECIAL FEATURE Free Spins, using the current page, the RTP for those spins will be as mentioned, over 3000%.
We recommend giving the SPECIAL FEATURE freespins on very rare occasions, preferably to VIP Players.

📜 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": "2024-01-01", "fs_type": "freebet", "apiusername": "your_api_username", "apipass": "your_api_password", "uniqid":"oiahtog12793g5497agwe9751515as5y1" }
📥 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. 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. Check via command 24 for games with "freespins": 1.

string

*freespins

✅

Number of freespins 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

*totalwinlimit

✅

Win cap. If > 0, any excess winnings are forfeited after freespins. 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 freespins. Use format: Y-m-d. After this date, freespins are no longer usable.

string

unlock_limit

❌

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

integer

fs_type

❌

Can be "freebet" (main spin, low RTP) or "vipfs" (special feature, high RTP). If omitted, vipfs (special feature) is used by default.

string

*apiusername

✅

Your API username

string

*apipass

✅

Your API password

string

*uniqid

✅

A unique grant identifier generated by you, one per grant. This makes the call idempotent: if a request times out and you resend it with the same uniqid, the original grant is returned instead of creating a duplicate. Reusing a uniqid never creates a second freespin/freebet grant. (Unique per operator.)

string

You must provide either login or userid — not both.

📃 Sample JSON Response (returned by RGS-CWS)

✅ Success:

{ "status": "OK", "freespins_id": "FS000198823" }

❌ 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

❌

If status = ERROR, message provides the reason (e.g., validation failure)

string

*freespins_id

✅

Unique ID for the freespins session. Note: This is not the same as the gameplay ID, which is generated after the user starts playing.

string

✅ 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.

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

  • After freespins 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 freespins are sent via a balance_adj request with type=win, but only after all freespins have been completed.