Free spins

Grant a player free spins on games of one provider. The player finds them in the game.

POST

`/v1/free-spins`

Grant free spins. Idempotent on reference.

SignedSandboxProduction

Field	Type	Required	Description
player_id	string	yes	Your player reference.
currency	string	yes	ISO 4217.
game_ids	string[]	yes	1 to 50 catalogue game IDs from `GET /v1/games`, all of one provider.
quantity	integer	yes	1..10000 spins.
bet_amount	string (money)	yes	Stake of one spin. Pick it from `GET /v1/free-spins/bet-options`.Example: `"0.20"`
valid_until	string (date-time)	yes	In the future, at most 90 days away.
reference	string	yes	Your id for the grant, up to 120 characters. A repeat under it answers the first grant.

request

{
  "player_id": "p-1",
  "currency": "EUR",
  "game_ids": ["6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10"],
  "quantity": 10,
  "bet_amount": "0.20",
  "valid_until": "2026-10-31T00:00:00Z",
  "reference": "promo-7"
}

response 200

{
  "id": "3333c0de-…",
  "free_spins_id": "promo-7",
  "status": "active",                  // active | finished | cancelled
  "player_id": "p-1",
  "currency": "EUR",
  "game_ids": ["vs20fruitsw"],         // game provider codes, as the series was placed
  "quantity": 10,
  "bet_amount": "0.20",
  "valid_until": "2026-10-31T00:00:00Z",
  "reference": "promo-7",
  "created_at": "2026-09-29T12:00:00Z",
  "finished_at": null,
  "cancelled_at": null,
  "win_amount": null                   // total paid, where the provider settles the series in one call
}

Possible errors

error	HTTP	Retry	When
VALIDATION_FAILED	422	no	A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse.
FREE_SPINS_REFUSED	409	no	The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason.
GAME_UNAVAILABLE	409	no	The game is not in your window, whether or not it exists.

Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.

Notes

free_spins_id is what your wallet sees on the bets and wins of the series. It is your reference when that is plain (letters, digits, _ . : -, at most 64 characters) and not yet used; otherwise an id of ours.
Games that cannot be granted together answer FREE_SPINS_REFUSED. Place them as separate grants.
Your wallet sees the play as bet and win carrying free_spins_id. Take nothing for the bet; book the win as bonus money.

Accepted stakes

GET

`/v1/free-spins/bet-options?game_id={id}&currency={code}`

Stakes the game provider accepts for a grant on this game, lowest first.

SignedSandboxProduction

response 200

{ "game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10", "currency": "EUR", "amounts": ["0.10", "0.20", "0.50", "1.00"] }

Possible errors

error	HTTP	Retry	When
FREE_SPINS_REFUSED	409	no	The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason.
GAME_UNAVAILABLE	409	no	The game is not in your window, whether or not it exists.

Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.

Read a grant

GET

`/v1/free-spins/{id}`

The grant as it stands; status becomes finished when a provider that settles in one call has paid it.

SignedSandboxProduction

Possible errors

error	HTTP	Retry	When
NOT_FOUND	404	no	No such session, grant, bonus campaign, transaction or round for your operator.

Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.

GET

`/v1/free-spins?reference={reference}`

Find a grant by your reference. There is no list call.

SignedSandboxProduction

Possible errors

error	HTTP	Retry	When
NOT_FOUND	404	no	No such session, grant, bonus campaign, transaction or round for your operator.

Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.

Cancel a grant

POST

`/v1/free-spins/{id}/cancel`

Withdraw a series still playable. Idempotent: a repeat answers the same grant.

SignedSandboxProduction

Spins already played stay played and what was won stays won. The answer is the grant with status: "cancelled".

Possible errors

error	HTTP	Retry	When
NOT_FOUND	404	no	No such session, grant, bonus campaign, transaction or round for your operator.
FREE_SPINS_REFUSED	409	no	The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason.

Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.