Integration Guide

Everything your dev team needs to add NextGen Instant Games to a sweepstakes platform. The games are hosted by NextGenDev.Games — you only integrate two things: a launch call and a seamless wallet.

Overview

1. Your server calls POST /api/v1/launch with the player and game. You get back a one-time game URL.
2. You open that URL in an iframe (or new tab) for the player.
3. While the player plays, our server calls your wallet endpoints to check balance, debit bets and credit wins. Your wallet stays the single source of truth.

You will receive from NextGenDev.Games: an Operator ID (e.g. op_yourbrand), an API secret, and the base URL of the game server. Amounts are always integers in minor units (cents): 1250 = 12.50.

Gold Coins & Sweeps Coins

Both are supported on the same operator account. Pass "currency": "GC" or "currency": "SC" when you launch a game; if you leave it out, your account’s default currency is used. The currency is sent back to you on every wallet call, so your wallet debits and credits the right balance.

• Each currency has its own separate jackpot pools in Lamp of Fortunes — Gold Coin play never grows a Sweeps Coin jackpot.
• Bet limits, RTP and max win are set per operator (and can be overridden per game) by NextGenDev.Games.
• The player sees the currency code next to their balance in every game.

Request signing (both directions)

Every request is signed with HMAC-SHA256 using your API secret. The same scheme is used for your calls to us and our calls to your wallet.

// Node.js
import crypto from "node:crypto";
function sign(secret, rawBody) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const sig = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return { "X-NGG-Timestamp": ts, "X-NGG-Signature": sig };
}
// Verify (on your wallet endpoints): recompute and compare with crypto.timingSafeEqual, check timestamp is within 300s.

1. Launch a game

POST {GAME_SERVER}/api/v1/launch

{
  "player_id": "12345",          // your player's unique ID (string)
  "game_id": "plinko",           // see Game IDs
  "mode": "real",                // "real" uses your wallet, "demo" uses free play credits
  "currency": "SC",              // optional: "SC" (Sweeps Coins) or "GC" (Gold Coins); defaults to your account currency
  "return_url": "https://yourbrand.com/lobby"    // optional: shows a "Lobby" button in the game
}

Response:

{ "token": "9f1c…", "url": "https://{GAME_SERVER}/play/plinko?token=9f1c…", "expires_in": 14400 }

// Node.js example
const body = JSON.stringify({ player_id: user.id, game_id: "mines", mode: "real" });
const res = await fetch(GAME_SERVER + "/api/v1/launch", {
  method: "POST",
  headers: { "content-type": "application/json", "X-Operator-Id": OPERATOR_ID, ...sign(API_SECRET, body) },
  body,
});
const { url } = await res.json();   // -> put this in the iframe

Never call launch from the browser — the API secret must stay on your server.

2. Embed the game

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

The games are responsive (desktop and mobile). Sessions last 4 hours; request a new URL each time a player opens a game.

3. Wallet callbacks (you implement these)

Our server sends signed POST requests with JSON bodies to {your wallet_url}/balance, /debit, /credit and /rollback. Respond within 8 seconds with HTTP 200 and { "balance": <integer minor units> }.

// Example debit request we send you
POST https://yourbrand.com/ngg-wallet/debit
X-NGG-Timestamp: 1791700000
X-NGG-Signature: 5c0f…
{ "operator_id": "op_yourbrand", "player_id": "12345", "currency": "SC",
  "transaction_id": "3b0d…:debit", "round_id": "3b0d…", "amount": 100, "game_id": "plinko" }

// Your success response
{ "balance": 48900 }

// Your error response (HTTP 4xx)
{ "error": "INSUFFICIENT_FUNDS" }

Rules your wallet must follow

• Idempotency: transaction_id is unique. If you receive the same one again, do not apply it twice — just return the current balance.
• Rollback: reverse the referenced debit if you applied it. If you never saw that debit, just return the balance with HTTP 200.
• Credits are retried until you return 200 — never reject a credit for a round you debited.
• Return INSUFFICIENT_FUNDS (HTTP 402 or 400) when the balance is too low; other errors cancel the bet.
• Always verify the signature and timestamp before touching balances.

Round lookup (for support & reconciliation)

POST /api/v1/rounds (signed) with { "round_id": "…" } or { "player_id": "12345", "limit": 50 }. Returns bet, payout, multiplier, status, the full outcome and provably-fair nonce for each round.

Games, RTP & limits

* Theoretical maximum. Every payout is capped by your max win per round.

All limits are set per operator and can be overridden per game. The current values are shown to players in each game’s Quick Rules.

Max win cap

Every round’s payout is limited to your operator’s max win per round, enforced on the game server before we credit your wallet. Games with very high theoretical multipliers (Rocket Rush, Limbo, Gem Mines, Sky Temple, Hi-Lo streaks) can never pay more than this cap, so one lucky round can’t wipe out a balance. Tell us the cap you want for GC and SC and we set it on your account.

Lamp of Fortunes jackpots

• Who funds it: 1.5% of every Lamp of Fortunes bet goes into the three pools. That 1.5% is already inside the game’s 96% RTP: the base game is tuned to 94.5% and the contributions make up the rest. The only extra is each pool’s starting value (the seed), which the operator funds — when a jackpot is hit it resets to its seed, and the win is paid through your normal wallet credit like any other win.
• Who shares it: pools are private to your operator account and separate per currency (GC and SC). They are not shared with other operators.
• How a player wins: each play has a chance to light the jackpot strip. A jackpot win is credited to your wallet as part of that round’s payout, and is listed in round lookup and in the admin reports.
• * Full odds apply at a bet of 5.00 or more; smaller bets have proportionally smaller jackpot odds (shown to the player in the game). Seeds, contribution rates and the reference bet can be changed per operator.

Provably fair

Every result comes from HMAC-SHA256 of a server seed (committed by its hash before play) and the player’s client seed and nonce. Players can rotate seeds in any game and check past rounds on the public round verifier, which is a good trust signal you can link to from your own site.

Error codes

Go-live checklist

1. Launch works with mode: "demo" (no wallet needed).
2. Wallet endpoints verify signatures and are idempotent.
3. Test: bet → win, bet → lose, insufficient funds, duplicate transaction_id, rollback.
4. Reconcile a day of rounds with /api/v1/rounds.
5. Send your wallet URL to NextGenDev.Games to switch to real mode.

Questions: support@nextgendev.games · NEXTGENGAMES LLC