Platform Documents · 03 / 04
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.
01 · The concept
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.
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
| Moment | Behavior |
|---|---|
| In the lobby | A free-spins badge shows the player's total available rounds; each eligible stake tier carries its own per-tier badge. |
| On join | If the player joins a tier with a matching grant, one free round is consumed automatically — no separate "use bonus" step. |
| In the round | The round plays exactly like a paid one; other players cannot tell who is on a free spin. |
| On win | The payout is credited as real money, the same amount a paid player would receive. |
| On expiry | Rounds unused by the grant's validity timestamp lapse silently. |
03 · Grant API
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.
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.| Field | Required | Notes |
|---|---|---|
| playerId | yes | The operator's player id — the same id used at game launch. |
| currency | yes | Wallet currency of the grant, e.g. USD. |
| externalReferenceId | yes | Your reference; echoed back on win settlement and used as the idempotency key. |
| numberOfFreeRounds | yes | How many rounds the grant contains (string, e.g. "10"). |
| freeRoundValidity | yes | Expiry, dd-MM-yyyy HH:mm:ss, UTC. |
| games | yes | Array of { gameId, betValue }. gameId is Predictor's game code (provided at onboarding); betValue is the stake tier the rounds apply to. |
| wagerRequirement | no | Optional integer, passed through for your bonus accounting. |
| Rule | Why |
|---|---|
| betValue must equal a live stake tier | Free 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 matching | A grant is matched on player id + currency + game + stake value. All four must line up with the session the player launches with. |
| Idempotency | Re-sending the same externalReferenceId for the same game does not duplicate the grant. |
| err_code | Meaning |
|---|---|
| 0 | Success — the grant is stored and live. |
| 200 | Invalid or missing parameters. |
| 8 | Authentication / signature failure. |
| 130 | General error. |
04 · Settlement
| Event | Operation | Amount |
|---|---|---|
| Join on free round | Free-bet flow / zero-amount bet | 0 — nothing debited; one grant round consumed |
| Win settlement | Standard win operation | + payout, real money; carries the grant's externalReferenceId |
| Loss | Standard 0-amount settlement | 0 |
| Round voids refund case | No money movement | 0 — 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.