← All docs

Fox Reel Studio Game Integration Guide

Version 2.0 · For operator casinos embedding Fox Reel Studio games.

This guide covers launching and embedding games. Wallet integration, authentication/signing, environments, and IP whitelisting are covered in the companion Integration Guide (INTEGRATION_GUIDE.md) — complete that first; game launches use the same signed API.

1. Game catalog

The live list, with descriptions and thumbnails, is always GET /api/games (Section 1a). Every game supports free spins and the progressive bonus module. RTP is set per game within your contracted range (80–99%, default per game); GET /api/v1/games returns the RTP you run.

Stateful games (Mines, Streak Flip, Ascent, Constellation, Jaws of Fortune, Nuke Nope! and others) keep a round open across several player actions until the player cashes out or busts. Only one open round per player session. The round record shows the full board and every action, for dispute resolution.

New games are announced with their game_code, RTP range and volatility before release. Per-game bet limits (min and max bet) are yours to set in the portal; max win is set per contract. Bets outside the limits are rejected in-game with BET_LIMIT, never silently clamped.

test-game is a bare page that drives every wallet operation with a visible request and response log. Use it for certification and disable it in production from the portal's Games page.

1a. Games catalog (build your lobby)

Public, no auth. Safe to call straight from a lobby page:

GET https://api.foxreelstudio.com/api/games?operator=<your-operator-code>

200 → {
  "provider": "Fox Reel Studio",
  "count": 19,
  "games": [
    {
      "code": "dice",
      "title": "Dice",
      "description": "Roll over or under your target …",
      "category": "instant",
      "thumbnail": "https://lockeandcrow-games.s3.eu-west-1.amazonaws.com/thumbnails/dice.jpg",
      "rtp_default": 99.0,
      "features": ["provably-fair", "auto-bet", "free-spins"],
      "launch_code": "dice"
    }
  ]
}

• With ?operator=<code> the list leaves out games you have disabled. Without it you get every game Fox Reel Studio has live. An unknown or suspended code returns an empty list.
• The response is cached for 60 seconds (Cache-Control: public, max-age=60), so a game you disable leaves your lobby within a minute.
• Use launch_code as the game_code when launching.

Signed, from your backend. GET /api/v1/games returns the same games plus your rtp, min_bet, max_bet and max_win per game. Sign it like any other API call, with an empty body (Integration Guide §4 and §5a).

2. Launching a game

Your backend (never the browser — the call is HMAC-signed) requests a launch URL, then your frontend opens it:

POST /api/v1/launch          (signed; see Integration Guide §4)
{
  "player_id":  "your-stable-player-id",
  "game_code":  "dice",
  "currency":   "USD",          // optional, defaults to account currency
  "lang":       "en",           // optional
  "brand_code": "lucky-red"     // optional, if brands are registered
}

200 → { "status": "OK", "url": "https://…/launch/<token>" }

Rules:

• The URL is single-session and tied to one player and one game. Request a fresh URL every time the player opens a game — do not cache or share URLs between players.
• Sessions last up to 4 hours (shorter if you set session_minutes for the player — see Integration Guide §7c). An expired session shows a "session expired" screen; relaunch to continue.
• Errors: UNKNOWN_GAME (bad code), GAME_DISABLED (disabled for you, or withdrawn by Fox Reel Studio), UNKNOWN_BRAND (unregistered brand_code), CURRENCY_MISMATCH (the player_id already plays in another currency).
• If a game is disabled while a player is in it, further bets in that open session are rejected and the game shows "Game unavailable".

3. Embedding

Open the launch URL as a full-page redirect or inside an iframe:

<iframe
  src="{launch_url}"
  style="width:100%; height:100%; border:0"
  allow="fullscreen"
></iframe>

• Games are responsive and mobile-first; give the iframe the full available viewport (position: fixed container or 100vh) for best results.
• Serve your wrapper page over HTTPS in production (mixed content will be blocked by browsers).
• Do not overlay UI on top of the game area; place your lobby/back button outside the iframe.
• One active game session per iframe. Navigating away simply abandons the session; any in-flight win settlement completes server-side regardless.

4. Money display

All amounts on the wire are integer minor units (cents). In-game the player sees decimal amounts in the session currency. The balance shown in the game is authoritative from the wallet:

• Seamless accounts: it is your balance, fetched via your /balance callback — if your callback is slow, the game feels slow. Keep p95 under 500 ms.
• Transfer accounts: it is the play-wallet balance held with us.

5. Free spins in games

When you award free spins (POST /api/v1/freespins/award, Integration Guide §7b) for a game, the game automatically:

1. shows the player their remaining free spins and the fixed bet size,
2. consumes spins before real money — no wallet debit occurs,
3. credits wins through the normal wallet path.

No frontend work on your side. Awards are per-player per-game; unused spins expire at expires_at if set.

With the progressive bonus module ("mode": "bonus", Integration Guide §7b) every game additionally shows a gift icon in its top bar with a bonus drawer: claim popover on entry, remaining free bets and pot during play, wagering progress bar, rules ("Bonus Rules" info button) and the "Get bonus money" collect step. All of it lives inside the game iframe.

6. Provably fair (what to tell your players)

Every game is provably fair. In the game footer players can:

• see the SHA-256 commitment of the current server seed before playing,
• set their own client seed (their entropy, our seed can't adapt to it),
• rotate the seed pair, which reveals the previous server seed,
• open the public verifier at {base_url}/fair (no login) and recompute every roll: roll = HMAC-SHA256(server_seed, client_seed + ":" + nonce), first 4 bytes mod 10000, ÷ 100.

You may link to the verifier from your own fairness page. Each game's rules screen states how rolls map to outcomes (coin flip: roll < 50 = heads).

For disputes: give us the round_id (returned in every bet response and visible in the portal under Rounds). We can produce the complete round record — bet, win, roll, nonce, seeds — for any round, indefinitely.

7. In-game statuses your support team may hear about

8. Per-game certification checklist

Run on staging for each game before it is enabled in production:

• Launch from your backend, open on desktop and one mobile device
• Balance displays correctly (matches your wallet)
• Winning and losing rounds settle correctly in your wallet
• Award free spins → game shows and consumes them, win credits arrive
• Bet above your max limit is rejected in-game (not clamped)
• Seed rotate → previous seed verifies on {base_url}/fair
• Your reconciliation for the test day matches our GGR report

When the checklist passes, enable the game in production from the portal's Games page, or ask us at [email protected].