PREDICTOR

Platform Documents · 03 / 04

Free Spins

How operators grant stake-free rounds, how a free round plays and settles, and the grant API your bonus engine calls — one endpoint, idempotent, per-player.

Granted with one API call Winnings are real money Matched per stake tier

01 · The concept

A free seat in a real game

A free spin is one stake-free entry into a normal paid round of a fixed stake size. Free players join the same lobbies as everyone else — same pot, same opponents, same rules — but their stake is not charged to their balance. Any winnings pay out as real money through the standard win operation.

Operator
Grant
The bonus engine grants N free rounds of a fixed stake value to a player via the creation endpoint.
→
Player
Join free
Joining a lobby of the matching stake consumes one round; the game shows a free-spin badge on eligible tiers.
→
Settlement
Real winnings
A winning free round pays the normal payout; the win settlement echoes the grant's reference id for your reconciliation.

Funding follows your wallet model: platforms with a free-bet API receive the free-spin withdraw/deposit pair; platforms without one receive a zero-amount bet so the round settles through the standard win flow. Either way the player experience is identical.

02 · Player experience

Visible, matched, spent automatically

MomentBehavior
In the lobbyA free-spins badge shows the player's total available rounds; each eligible stake tier carries its own per-tier badge.
On joinIf the player joins a tier with a matching grant, one free round is consumed automatically — no separate "use bonus" step.
In the roundThe round plays exactly like a paid one; other players cannot tell who is on a free spin.
On winThe payout is credited as real money, the same amount a paid player would receive.
On expiryRounds unused by the grant's validity timestamp lapse silently.

03 · Grant API

Creating free spins

Your bonus engine calls one endpoint on the Predictor API host (provided during onboarding). Requests use a signed envelope; the signing key is exchanged at onboarding.

POST /api/freespins/create Content-Type: application/json { "time": "dd-MM-yyyy HH:mm:ss", "data": { …payload… }, "hash": "MD5(privateKey + time + data)" }
Time format. time and freeRoundValidity use dd-MM-yyyy HH:mm:ss (for example 09-04-2026 13:04:48) — day first, not a unix timestamp. The hash is hex, lowercase, computed over the key, the time string and the exact JSON of data.

Payload fields

FieldRequiredNotes
playerIdyesThe operator's player id — the same id used at game launch.
currencyyesWallet currency of the grant, e.g. USD.
externalReferenceIdyesYour reference; echoed back on win settlement and used as the idempotency key.
numberOfFreeRoundsyesHow many rounds the grant contains (string, e.g. "10").
freeRoundValidityyesExpiry, dd-MM-yyyy HH:mm:ss, UTC.
gamesyesArray of { gameId, betValue }. gameId is Predictor's game code (provided at onboarding); betValue is the stake tier the rounds apply to.
wagerRequirementnoOptional integer, passed through for your bonus accounting.

Constraints

RuleWhy
betValue must equal a live stake tierFree rounds are consumed by joining a lobby of exactly that stake in the grant's currency (standard tiers: 1 / 2 / 5 / 10). A betValue that matches no tier can never be consumed.
Exact matchingA grant is matched on player id + currency + game + stake value. All four must line up with the session the player launches with.
IdempotencyRe-sending the same externalReferenceId for the same game does not duplicate the grant.

Response

{ "referenceId": "…", "result": true, "err_desc": null, "err_code": 0 } { "referenceId": null, "result": false, "err_desc": "…", "err_code": 200 }
err_codeMeaning
0Success — the grant is stored and live.
200Invalid or missing parameters.
8Authentication / signature failure.
130General error.

04 · Settlement

How a free round moves money

EventOperationAmount
Join on free roundFree-bet flow / zero-amount bet0 — nothing debited; one grant round consumed
Win settlementStandard win operation+ payout, real money; carries the grant's externalReferenceId
LossStandard 0-amount settlement0
Round voids refund caseNo money movement0 — nothing was staked

Because the win settlement echoes your externalReferenceId, your bonus engine can attribute every free-spin payout to the grant that funded it, line by line.