API Documentation

BigBang Casino API is a B2B game aggregator that lets you integrate 45+ game providers and 6,000+ casino games — in two tiers, Standard (in-house / emulated) and Premium (Reeltrix real-money providers) — through a single REST API. Filter any catalog call with ?type=standard or ?type=premium. The exact catalog and providers your key can access depend on your plan and shop configuration — always read the live catalog from the API rather than hard-coding it.

Quick start: Sign up at /portal, grab your API key, call GET /api/v1/games to browse the catalog, then POST /api/v1/games/launch to generate a signed game URL. Pick a wallet model (managed transfer or seamless callbacks) and go live.

Integrate with an AI agent

The whole contract on this page is also published as one machine-readable file, /docs/agent.md (indexed in /llms.txt). It is written for coding agents: endpoints, the launch flow, the seamless-wallet callbacks with the exact signature rules, the round contract, a reference implementation, a build plan and acceptance tests. Give your agent this one line and it can build the integration end to end:

Read https://api.bigbangcasino.bet/docs/agent.md and integrate the BigBang Casino API into this project end to end: catalog sync, game launch in an iframe, and the seamless wallet callbacks (user_data + balance_change with HMAC verification, idempotency and round_end). My API key is in the env var BIGBANG_API_KEY.

Works with Claude Code, Cursor, GitHub Copilot, ChatGPT, Gemini, Windsurf, Aider — anything that can fetch a URL. For an agent without web access, download the spec into the repo and tell it to read the file:

# then: "Read BIGBANG_AGENT.md and integrate the BigBang Casino API into this project"
curl -sL https://api.bigbangcasino.bet/docs/agent.md -o BIGBANG_AGENT.md

Instructions for any AI agent reading this page: fetch https://api.bigbangcasino.bet/docs/agent.md and follow its Plan section in order — catalog, players, launch, then the wallet. Verify every balance_change signature exactly as specified there (the amount is concatenated in its shortest JS-style form), apply movements idempotently on transaction_id, accept amount: 0, close rounds on round_end: true, and never expose the API key client-side. Ask the operator once for anything the brief leaves to them (stack, wallet model, sandbox key), then proceed.

Authentication

Every API request requires an API key, passed in the X-API-Key header (a query/body parameter api_key is also accepted as a fallback). Generate and rotate keys from the Dashboard. All calls should be server-to-server.

# Every request must include your API key
curl https://api.bigbangcasino.bet/api/v1/games \
  -H "X-API-Key: YOUR_API_KEY"

Header	Value	Required
`X-API-Key`	Your API key (fallback: `?api_key=` query param)	Required
`Content-Type`	`application/json`	Required for POST

Key type	Format	Access
Live	Opaque token (e.g. `87UcWmlKrtVTQXte…`) — no fixed prefix	Standard + Premium tiers (Premium requires a funded balance)
Sandbox	Prefixed with `ek_test_`	Standard providers only; Premium (Reeltrix) games are blocked

Keys can be scoped from the Dashboard: an IP allow-list, a domain lock (Origin/Referer host), per-key permission flags (can_read_games, can_launch_games, can_manage_balance, can_view_stats), and provider / game allow-and-block lists. A request that violates any of these returns 401 or 403.

Keep your key secret. Never expose it in client-side code. All API calls should be made server-to-server. The key doubles as the HMAC secret for signed launch URLs and wallet callbacks — if it is compromised, rotate it immediately from the Dashboard.

Base URL

All REST endpoints live under the /api/v1 prefix:

https://api.bigbangcasino.bet/api/v1

All requests and responses use JSON. Monetary amounts are numeric (2-decimal) values in the player's account currency. Every response is wrapped in a success envelope (see Error Handling).

Rate Limits

Each key carries a technical per-minute and per-hour request throttle (configurable per plan from the Dashboard). Billing is on GGR (a % of monthly bets−wins per provider) — not per request or per launch, so game launches are unlimited:

Key	Throttle	Game launches
Sandbox (`ek_test_`)	Per-key limit	Free — 100,000 virtual balance (auto)
Live	Per-plan limit	Unlimited — billed on GGR
Enterprise	Custom	Unlimited — custom GGR rates

When you exceed the throttle the API returns 429 Too Many Requests.

Error Handling

The API uses standard HTTP status codes. Every response carries a success boolean; errors add an error object whose code mirrors the HTTP status:

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

Status	Meaning
`200`	Success (`201` on user creation)
`400`	Bad request — validation failed, game/user not found, insufficient balance
`401`	Unauthorized — missing, invalid, inactive or expired API key
`403`	Forbidden — key lacks permission, IP/domain blocked, or Premium game on a sandbox key
`404`	Not found — game, user or resource does not exist
`429`	Rate limit exceeded
`500`	Internal server error

List Games

GET /api/v1/games

Returns the game catalog visible to your key, deduplicated by name and filterable. Requires the can_read_games permission.

Query Parameters

Param	Type	Description
`category`	string	Optional Filter by category title, slug/href or id (e.g. `Pragmatic`)
`provider`	string	Optional Filter by provider; resolves to a category, else matches games whose name starts with it
`search`	string	Optional Substring match on game name
`type` / `mode`	string	Optional `standard` or `premium`. Each game also returns a `mode` field and `is_premium` boolean.
Response field `game_type` — `slot` \| `live` \| `crash`. Live-dealer tables are `live`, crash / instant games are `crash`, everything else (slots, RNG table games) is `slot`. Filter client-side on this field; there is no separate live-games endpoint.
`limit`	integer	Optional Results per page (default `100`, max `5000`)
`offset`	integer	Optional Row offset for pagination (default `0`)

Example Request

curl "https://api.bigbangcasino.bet/api/v1/games?provider=Habanero&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

# Premium tier only (Reeltrix real-money providers)
curl "https://api.bigbangcasino.bet/api/v1/games?type=premium&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 4821,
      "name": "SGHotHotFruit",
      "title": "Hot Hot Fruit",
      "provider": "Habanero",
      "category": "Habanero",
      "category_title": "Habanero",
      "thumbnail": "https://bigbangcasino.bet/frontend/Vegas/ico/Habanero/SGHotHotFruit.webp?v=1699999999",
      "mode": "standard",
      "is_premium": false,
      "game_type": "slot",
      "is_demo": false
    }
  ],
  "pagination": { "total": 1420, "limit": 20, "offset": 0 }
}

name is the game's launch identifier — a stable slug (often CamelCase, all-lowercase for some providers such as PG Soft) that is not meant to be shown to players. Display title instead; it is the human-readable name (e.g. "Alibabas Cave Of Fortune" for name: "alibabascaveoffortune").

thumbnail is a fully-qualified URL (or null if no icon exists). With no category/provider/search filter, results are shuffled by a daily seed so "all games" looks mixed while pagination stays stable.

Game Detail

GET /api/v1/games/:id

Returns metadata for a single game by its numeric ID. Requires can_read_games. Returns 404 if the game does not exist for your shop, or 403 if it is not enabled for your key.

Example Response

{
  "success": true,
  "data": {
    "id": 4821,
    "name": "SGHotHotFruit",
    "title": "Hot Hot Fruit",
    "provider": "Habanero",
    "category": "Habanero",
    "category_title": "Habanero",
    "thumbnail": "https://bigbangcasino.bet/frontend/Vegas/ico/Habanero/SGHotHotFruit.webp?v=1699999999",
    "description": "",
    "is_demo": false
  }
}

List Providers

GET /api/v1/categories

Returns the providers (categories) available to your key. Requires can_read_games. The slug is the exact value you pass to ?category= or ?provider= on GET /games. Sandbox keys never see Premium categories.

Example Response

{
  "success": true,
  "data": [
    { "id": 38, "name": "Pragmatic",      "slug": "Pragmatic",      "premium": false },
    { "id": 39, "name": "Greentube",      "slug": "Greentube",      "premium": false },
    { "id": 91, "name": "Pragmatic Play", "slug": "PragmaticPlay", "premium": true }
  ]
}

Launch Game

POST /api/v1/games/launch

Generates a signed, ready-to-embed game URL for a player. Requires the can_launch_games permission. The returned game_url loads the game in an iframe; money then moves through your chosen wallet model. Note: a short alias POST /launch proxies to this same endpoint.

Request Body

Field	Type	Description
`game_id`	integer	Required Numeric game ID (from `GET /games`)
`user_token`	string	Required for real mode. Your unique player identifier (matched against the player you created). Use `"demo"` or `"guest"` — or omit with `demo:true` — for demo mode.
`demo`	boolean	Optional `true` launches fun mode (virtual balance, no wallet)
`language`	string	Optional ISO 639-1 code (default `en`); a region suffix is accepted and ignored (`pt-BR` → `pt`). Passed to the game client. A game that has no UI translation for the requested code falls back to English rather than failing to load — support is per provider and per game. Portuguese (`pt`) is currently available for Pragmatic (552 titles), Hacksaw, Booming, Playtech, Blueprint, Evoplay, Amatic, Habanero, Fazi (all titles of each), PG Soft (104), Platipus (25) and Bellink (16). The same providers except PG Soft and Pragmatic also accept most European codes (es, de, fr, it, ru, tr, …). Other providers (Greentube, Novamatic, Synot, Gamomat, Playson, JILI, Kajot) show English.
`return_url`	string	Optional URL to redirect to when the player exits
`device`	string	Optional Premium/Reeltrix only — `desktop` (default) or `mobile`
`home_url`	string	Optional Premium/Reeltrix only — lobby URL for the in-game home button

Example Request

curl -X POST "https://api.bigbangcasino.bet/api/v1/games/launch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": 4821,
    "user_token": "player_42",
    "language": "en",
    "return_url": "https://your-site.com/casino"
  }'

Example Response (standard game)

{
  "success": true,
  "game_url": "https://bigbangcasino.bet/api/game/Habanero/SGHotHotFruit/1481/player_42/1699999999/ab12cd…",
  "session_id": "9f8e7d6c5b4a…",
  "game_id": 4821,
  "game_name": "SGHotHotFruit"
}

The game_url is HMAC-signed with your API key and carries the player session into the game engine. Premium (Reeltrix) launches return a game_url pointing at the aggregator plus a provider field, and no session_id.

Embedding: Load game_url in an iframe (allow="autoplay; fullscreen"). If the player does not exist yet, create them first via POST /users/create — a real-money launch for an unknown user_token returns 400 "User not found" (unless your key has a seamless user_data endpoint that auto-provisions them).

Demo Mode

Set demo: true (or user_token: "demo"). No wallet is involved — the game runs on a virtual balance. Useful for storefronts, review sites and testing.

curl -X POST "https://api.bigbangcasino.bet/api/v1/games/launch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "game_id": 4821, "demo": true }'

// Response
{
  "success": true,
  "game_url": "https://bigbangcasino.bet/demo/launch/Habanero/SGHotHotFruit?currency=EUR",
  "demo": true,
  "game_id": 4821,
  "game_name": "SGHotHotFruit"
}

Create Player

POST /api/v1/users/create

Registers a player under your account. Idempotent — creating an existing user_token returns 200 with "message": "User already exists"; a new player returns 201.

Request Body

Field	Type	Description
`user_token`	string	Required Your unique player identifier (max 255)
`username`	string	Optional Display username (defaults to `user_token`)
`country`	string	Optional ISO country code

{
  "success": true,
  "data": {
    "user_token": "player_42",
    "username": "player_42",
    "balance": 0.00,
    "currency": "EUR"
  }
}

Get Player

GET/api/v1/users/:user_token

Returns a player's profile and balance.

{
  "success": true,
  "data": {
    "user_token": "player_42",
    "username": "player_42",
    "balance": 100.50,
    "currency": "EUR",
    "status": 1,
    "country": "DE"
  }
}

Player History

GET/api/v1/users/:user_token/history

Returns a player's bet/win history. Requires can_view_stats.

Query Parameters

Param	Type	Description
`from`	datetime	Optional Include rounds on/after this time
`to`	datetime	Optional Include rounds on/before this time
`game_id`	string	Optional Filter by game name
`limit`	integer	Optional Max rows (default `50`, max `200`)

{
  "success": true,
  "data": [
    { "id": 55012, "game": "SGHotHotFruit", "bet": 1.00, "win": 2.50, "date_time": "2026-07-21T14:03:00+00:00" }
  ]
}

Get Balance

GET/api/v1/balance/:user_token

Returns a player's current balance (managed-wallet accounts).

{
  "success": true,
  "data": { "user_token": "player_42", "balance": 100.50, "currency": "EUR" }
}

Deposit

POST/api/v1/balance/deposit

Credits a managed-wallet player's balance. Requires can_manage_balance. Use a unique transaction_id for idempotency/audit.

Request Body

Field	Type	Description
`user_token`	string	Required
`amount`	number	Required ≥ 0.01
`transaction_id`	string	Required Your unique reference

{
  "success": true,
  "data": {
    "user_token": "player_42",
    "balance_before": 100.50,
    "balance_after": 150.50,
    "amount": 50.00,
    "transaction_id": "txn_abc123"
  }
}

Withdraw

POST/api/v1/balance/withdraw

Debits a managed-wallet player's balance. Requires can_manage_balance. Returns 400 "Insufficient balance" if the amount exceeds the balance. Same request body and response shape as deposit (balance_before / balance_after / amount / transaction_id).

Free Rounds

Give a player a number of free spins at a fixed stake on chosen Standard games — for example a welcome offer of 20 spins at 0.20 on Sweet Bonanza. Available on the Business and Scale plans; on Starter, creating a grant answers 403 with "reason": "plan_required". Listing and cancelling always work.

Supported games: Standard Pragmatic Play titles (provider Pragmatic in GET /games). More providers will follow; Premium games are not supported.
How a free round plays: every spin the player makes at exactly the granted bet in a granted game uses one round. The stake is not charged to your wallet; only the win is credited. Bonus buys, ante bets and other stake sizes are normal paid spins. Cascades, free spins and bonus games triggered by a free round are part of that round.
Players with no balance: a player who holds a grant can open the game at a balance of 0. While rounds remain and the real balance is below the stake, the game shows the balance plus one stake so the game lets them spin; your wallet is never charged for it.
Your wallet: a free round with a win arrives as a normal balance_change credit with bet_amount: 0, win_amount = the win and an extra free_round_id field (informational, not part of the field signature; covered by X-Body-Signature). A losing free round sends nothing.
Billing: free rounds count in GGR as bet 0 / win X — the wins are the cost of your promotion.
Tell the player which game and stake the free rounds are for; the game client shows the balance, not a free-round counter.

POST/api/v1/free-rounds

Creates a grant for one player. Requires can_launch_games. The player does not need to exist yet. Returns 201.

Request Body

Field	Type	Description
`user_token`	string	Required Your player identifier (as used for launches)
`game_ids`	int[]	Required 1–50 game ids from `GET /games`, all from the same provider (`game_id` for a single game also works)
`rounds`	int	Required Number of free rounds, 1–500
`bet`	number	Required Total stake per round in your shop currency. Must be a stake the player can select in every granted game — otherwise `400` with `"reason": "bet_not_allowed"` and the game's `allowed_bets`.
`valid_days`	int	Optional Validity in days, 1–90 (default 7)
`expires_at`	ISO 8601	Optional Exact expiry instead of `valid_days` (max 90 days ahead)
`campaign_id`	string	Optional Your reference, max 100. One grant per `campaign_id` and player — repeating it answers `409` with the existing grant, so retries are safe.

{
  "success": true,
  "data": {
    "id": 1287,
    "campaign_id": "welcome-oct",
    "user_token": "player_42",
    "provider": "Pragmatic",
    "games": ["SweetBonanza"],
    "bet": 0.20,
    "currency": "EUR",
    "rounds_total": 20,
    "rounds_left": 20,
    "rounds_used": 0,
    "win_total": 0.00,
    "status": "active",
    "expires_at": "2026-10-22T21:00:00+02:00",
    "created_at": "2026-10-15T21:00:00+02:00",
    "first_used_at": null,
    "last_used_at": null
  }
}

status: active, completed (all rounds used), cancelled or expired. win_total is the total credited to the player from the grant's rounds.

List grants

GET/api/v1/free-rounds

Your grants, newest first. Optional query filters: user_token, campaign_id, status (active / completed / cancelled / expired), limit (1–500, default 100). One grant: GET /api/v1/free-rounds/{id}.

Cancel a grant

POST/api/v1/free-rounds/{id}/cancel

Stops an active grant immediately (also DELETE /api/v1/free-rounds/{id}). Rounds already played and their wins stand. Returns the grant.

Seamless Wallet (Callbacks)

BigBang supports two wallet models, chosen by how your API key is configured in the Dashboard:

Managed / transfer wallet (default) — the balance lives with us. You pre-fund it with POST /balance/deposit and reclaim it with POST /balance/withdraw. No callback endpoints to build.
Seamless wallet — the balance stays authoritative on your side. You register two callback URLs on your key (user_data and balance_change); BigBang calls them during gameplay to read the balance and apply each bet/win in real time.

Money flow (seamless): Game engine → BigBang → your user_data URL (read balance) and balance_change URL (apply bet/win). Configure both URLs on your API key from the Dashboard; they are not passed per launch.

Signature

Every seamless callback carries a signature field. It is an HMAC-SHA256 hex digest, keyed with your API key, over the concatenated payload fields (not the raw body):

const crypto = require('crypto');

// balance_change signature = HMAC_SHA256(username + amount + game + game_category + transaction_id, API_KEY)
function sign(p, apiKey) {
  const base = p.username + p.amount + p.game + p.game_category + p.transaction_id;
  return crypto.createHmac('sha256', apiKey).update(base).digest('hex');
}

user_data — balance read

Called (HTTP GET) when a session needs the player's balance/identity. Return the current balance.

// Request from BigBang → your user_data URL
GET https://your-site.com/wallet/user?username=player_42

// Your response — any of these balance keys is accepted (top-level or under "data")
{ "username": "player_42", "balance": "1250.00", "currency": "EUR" }

balance_change — bet / win

Called (HTTP POST) for every balance movement. amount is negative for a bet (debit) and positive for a win (credit). Apply it idempotently on transaction_id and return the new balance.

// Request from BigBang → your balance_change URL
{
  "username": "player_42",
  "amount": -2.50,
  "game": "SGHotHotFruit",
  "game_category": "Habanero",
  "transaction_id": "66a3f1b2c…",
  "signature": "hmac_sha256_hex…",
  "round_id": "66a3f1b2c…",
  "type": "round",
  "round_end": true,
  "game_id": 214529,
  "provider_id": "Habanero",
  "bet_amount": 2.50,
  "win_amount": 0.00
}

// Your response — return the new balance (keys: balance / new_balance / user_balance, top-level or under "data")
{ "status": "ok", "balance": "1247.50" }

Idempotency: If you receive a duplicate transaction_id, do not apply it again — return the same balance. Sandbox (ek_test_) callbacks include "sandbox": true; your endpoint should skip real balance changes when it is set.

Identifying the game

game + game_category are display values and are not guaranteed unique. To map a movement back to your catalogue use the two identity fields (informational — not part of the signature):

Field	Meaning
`game_id`	The `id` of the game from `GET /api/v1/games` — the same value you passed to `POST /api/v1/games/launch`. Integer; `null` only if the title could not be resolved.
`provider_id`	The provider `slug` from `GET /api/v1/providers` (equal to the games list's `category`). String, e.g. `PGSoft`, `AmusnetLocal`.

Rounds — linking bets and wins

Every movement carries round_id, type and round_end (informational — not part of the signature):

Source	`type`	How a round arrives
Standard (self-hosted) games — most providers	`round`	One self-contained movement per round: `amount` is the net result (bet − win), `round_id` equals `transaction_id`, `round_end` is `true`.
Standard — PG Soft, JILI, Endorphina, Fugaso, Gamzix, Amusnet, Iconic21	`bet`, `win`, `refund`	Linked movements sharing one `round_id`: a negative `bet` (`round_end: false`), zero or more `win` movements (a PG Soft feature pays each free spin as it lands, `round_end: false` while the feature continues), and a final movement with `round_end: true` — a `win` (may be `0` on a loss) or a `refund` of a stake the round never used. A live table (Amusnet, Iconic21) may open the round with several `bet` movements before closing it once.
Premium games	`bet`, `win`, `refund`	Separate movements sharing the same `round_id`: a negative `bet` (`round_end: false`), then a `win` (may be `0`, `round_end: true`). A `refund` reverses an abandoned or cancelled bet, carries the original `round_id` and closes it (`round_end: true`).

round_end: true means no further movement will follow for this round_id — close the round in your ledger on that movement, whatever number of movements preceded it. Some operator wallets reject a 0 amount; if yours does, we detect the rejection, stop sending zero-amount wins to your endpoint for an hour and read your user_data endpoint instead to close the round — but then you receive no win for losing premium rounds, so accept amount: 0 if you want every round closed explicitly.

Gross bet and win (turnover)

A Standard movement's amount is often the net result of a round, so on a winning spin the stake is not visible in it. When the gross split is known, the movement also carries (informational — not part of the field signature, covered by X-Body-Signature):

Field	Meaning
`bet_amount`	Stake contained in this movement (≥ 0). Use it for turnover, rakeback and wagering.
`win_amount`	Win contained in this movement (≥ 0). Always `win_amount − bet_amount = amount`.

Examples: a one-save winning spin amount 1.50 → bet_amount 0.50, win_amount 2.00; a stake sent on its own amount −0.20 → bet_amount 0.20, win_amount 0; the matching win paid later amount 2.85 → bet_amount 0, win_amount 2.85. Count turnover as the sum of bet_amount. When a movement carries neither field the split could not be determined for certain and nothing is guessed — treat amount as before. Premium movements already separate stake (type: bet) and win (type: win).

Failures and retries

A call counts as failed when your endpoint returns a non-2xx status, times out (10 s), or replies without a usable balance. BigBang then:

retries 3 times immediately with exponential backoff (100 / 200 / 400 ms);
if still failing, stores the movement and replays it every hour, up to 12 attempts;
uses the same transaction_id on every retry — your endpoint must be idempotent so a late duplicate is acknowledged, not applied twice.

Pending (undelivered) movements for your key are visible to the AI assistant in the Dashboard; contact support to replay or discard them by hand.

Reference implementation

A minimal, complete seamless wallet: signature check, idempotency on transaction_id, insufficient-funds handling. Replace the storage calls with your own database.

Node.js (Express)

const express = require('express');
const crypto  = require('crypto');
const app = express(); app.use(express.json());

const API_KEY = process.env.BIGBANG_API_KEY;          // your live (or sandbox) key = HMAC secret
const balances = new Map([['player_42', 1250.00]]);   // replace with your DB
const applied  = new Map();                           // transaction_id -> balance after (idempotency)

// GET /wallet/user?username=...
app.get('/wallet/user', (req, res) => {
  const u = req.query.username;
  if (!balances.has(u)) return res.status(404).json({ error: 'unknown user' });
  res.json({ username: u, balance: balances.get(u).toFixed(2), currency: 'EUR' });
});

// POST /wallet/balance
app.post('/wallet/balance', (req, res) => {
  const p = req.body || {};
  const base = String(p.username) + String(p.amount) + String(p.game) + String(p.game_category) + String(p.transaction_id);
  const sig  = crypto.createHmac('sha256', API_KEY).update(base).digest('hex');
  if (sig !== p.signature) return res.status(401).json({ error: 'bad signature' });
  if (p.sandbox) return res.json({ status: 'ok', balance: '100000.00' });      // never touch real money
  if (applied.has(p.transaction_id))                                          // duplicate = same answer
    return res.json({ status: 'ok', balance: applied.get(p.transaction_id).toFixed(2), duplicate: true });
  if (!balances.has(p.username)) return res.status(404).json({ error: 'unknown user' });
  const amount = Number(p.amount);
  const next = Math.round((balances.get(p.username) + amount) * 100) / 100;
  if (next < 0) return res.status(400).json({ error: 'insufficient balance', balance: balances.get(p.username).toFixed(2) });
  balances.set(p.username, next);                       // in your DB: one transaction with the ledger insert
  applied.set(p.transaction_id, next);                  // p.round_id / p.type are available for your ledger
  res.json({ status: 'ok', balance: next.toFixed(2) });
});

app.listen(8080);

PHP

<?php
// user_data:  GET  /wallet/user.php?username=...
// balance_change: POST /wallet/balance.php  (JSON body)
$API_KEY = getenv('BIGBANG_API_KEY');
$pdo = new PDO('mysql:host=localhost;dbname=casino', 'user', 'pass');

if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    $u = $_GET['username'] ?? '';
    $bal = $pdo->prepare('SELECT balance FROM players WHERE username=?'); $bal->execute([$u]);
    if (($b = $bal->fetchColumn()) === false) { http_response_code(404); exit(json_encode(['error' => 'unknown user'])); }
    exit(json_encode(['username' => $u, 'balance' => number_format((float)$b, 2, '.', ''), 'currency' => 'EUR']));
}

$p = json_decode(file_get_contents('php://input'), true) ?: [];
$base = $p['username'] . $p['amount'] . $p['game'] . $p['game_category'] . $p['transaction_id'];
if (!hash_equals(hash_hmac('sha256', $base, $API_KEY), (string)($p['signature'] ?? ''))) {
    http_response_code(401); exit(json_encode(['error' => 'bad signature']));
}
if (!empty($p['sandbox'])) exit(json_encode(['status' => 'ok', 'balance' => '100000.00']));

$pdo->beginTransaction();
$dup = $pdo->prepare('SELECT balance_after FROM wallet_tx WHERE transaction_id=?'); $dup->execute([$p['transaction_id']]);
if (($prev = $dup->fetchColumn()) !== false) {                 // duplicate delivery: same answer, no change
    $pdo->commit(); exit(json_encode(['status' => 'ok', 'balance' => number_format((float)$prev, 2, '.', ''), 'duplicate' => true]));
}
$row = $pdo->prepare('SELECT balance FROM players WHERE username=? FOR UPDATE'); $row->execute([$p['username']]);
if (($cur = $row->fetchColumn()) === false) { $pdo->rollBack(); http_response_code(404); exit(json_encode(['error' => 'unknown user'])); }
$next = round((float)$cur + (float)$p['amount'], 2);
if ($next < 0) { $pdo->rollBack(); http_response_code(400); exit(json_encode(['error' => 'insufficient balance', 'balance' => number_format((float)$cur, 2, '.', '')])); }
$pdo->prepare('UPDATE players SET balance=? WHERE username=?')->execute([$next, $p['username']]);
$pdo->prepare('INSERT INTO wallet_tx (transaction_id, round_id, type, username, amount, game, balance_after) VALUES (?,?,?,?,?,?,?)')
    ->execute([$p['transaction_id'], $p['round_id'] ?? $p['transaction_id'], $p['type'] ?? 'round', $p['username'], $p['amount'], $p['game'], $next]);
$pdo->commit();
echo json_encode(['status' => 'ok', 'balance' => number_format($next, 2, '.', '')]);

Testing without money: set these two URLs on your sandbox key (ek_test_…) and launch any Standard game from the Dashboard — every callback arrives with "sandbox": true, so you can verify signatures, idempotency and error handling end-to-end for free.

API Keys

Manage keys from the Dashboard:

Live key — an opaque token (no fixed prefix) for production traffic.
Sandbox key (ek_test_…) — for development and testing; Standard providers only, free on all plans.

Rotating a key immediately invalidates the old one. The key value is also the HMAC secret used to sign launch URLs and to verify seamless-wallet callbacks — treat it as a secret.

Sandbox Mode

Use your ek_test_… key in place of the live key — same endpoints, no code changes. Sandbox serves Standard providers only; Premium (real-money Reeltrix) games return 403.

Feature	Sandbox	Live
API key	`ek_test_…` prefix	Opaque token
Player balance	Synthetic 100,000 (auto)	Managed balance or your seamless wallet
Providers	Standard only	Standard + Premium
Callbacks	Include `"sandbox": true`	Normal callbacks
Upfront balance	Not required (free)	Required for Premium
Cost	Free	GGR %-based (Standard low · Premium higher)

Usage & Billing

A prepaid balance is required for live (real-money) play. Fund your account from the Dashboard. Billing is on GGR — a percentage of each provider's monthly Gross Gaming Revenue (bets − wins), floored at 0 per provider — settled monthly and drawn from that prepaid balance. There is no per-request or per-launch quota; game launches are unlimited. Standard providers carry a low rate; Premium (real-money) providers a higher one. The Sandbox key (ek_test_) needs no balance and serves Standard providers only.

Webhooks

Configure a webhook URL and secret in the Dashboard to receive event notifications (separate from the money path):

session.started — a player opened a game (fired on standard real-money launch)
session.ended — a session closed or timed out
round.completed — a game round finished (summary)

Webhooks are signed with HMAC-SHA256 using your webhook secret.

Providers List

The aggregator carries 45+ providers. The exact set your key can launch is plan- and shop-dependent — always read the live list from GET /api/v1/categories. A representative selection:

Pragmatic — Standard

Pragmatic Play — Premium

Greentube — Standard

EGT Digital — Standard

Amusnet / EGT — Standard

Playtech — Standard

Habanero — Standard

BGaming — Standard

3 Oaks Gaming — Standard

PG Soft — Standard

Hacksaw Gaming — Standard

Nolimit City — Standard

ELK Studios — Standard

NetEnt — Standard

Push Gaming — Standard

Blueprint — Standard

Spinomenal — Standard

PenguinKing (Octoplay) — Standard

Endorphina — Standard

Merkur — Standard

Amatic — Standard

Novamatic — Standard

Fugaso — Standard

RubyPlay — Standard

Booming Games — Standard

Gamomat — Standard

Gamzix — Standard

Playson — Standard

Synot — Standard

Mascot Gaming — Standard

ELA Games — Standard

Evoplay — Standard

Inout Games — Standard

Tomhorn Gaming — Standard

PatePlay — Standard

Fazi — Standard

Platipus — Standard

Kajot — Standard

Bellink — Standard

CrashGames — Standard

Spribe — Standard

JILI — Standard

Pragmatic Live — LIVE Casino

VegasLive — LIVE Casino

Premium (Reeltrix real-money) providers require a funded live key. Standard providers run on our in-house / emulated engines. Sandbox keys (ek_test_) are limited to Standard providers.

Currencies

A player's balance is denominated in the currency of their account, set when you provision the player (default EUR). It is not passed per launch. Session currencies currently in use:

Currency	Code	Type
Euro	`EUR`	Fiat (default)
US Dollar	`USD`	Fiat
Indian Rupee	`INR`	Fiat
Coin (social / virtual)	`COIN`	Virtual

Additional currencies can be enabled per account on request. Crypto (USDT, BTC and others via NOWPayments) is used to fund your prepaid billing balance — it is not a per-player session currency.

Portal & Website Languages

The language field on launch selects the game client's UI, per provider. Separately, this website and your customer portal are available in 26 languages:

en English, de Deutsch, it Italiano, fr Français, es Español, sq Shqip, me Crnogorski, tr Türkçe, el Ελληνικά, sr Српски, zh 中文, pt Português, ru Русский, da Dansk, sv Svenska, bn বাংলা, bg Български, pl Polski, ro Română, cs Čeština, hu Magyar, sk Slovenčina, nl Nederlands, et Eesti, ar العربية, fa فارسی.

ar and fa are right-to-left. Public pages live at /<code>/ (for example /de/) with hreflang alternates. In the portal, the globe at the top right switches the language immediately and remembers it in this browser; Account Settings → Preferences saves a default on your account, and ?lang=<code> on the portal URL forces one for that visit. Dictionaries load on demand, one file per language.

Changelog

v1.11 — Oct 2026

Free rounds (Business and Scale plans): POST /api/v1/free-rounds grants a player free spins at a fixed stake on Standard Pragmatic Play games; wins arrive as credits with bet_amount: 0 and free_round_id.

v1.10 — Sep 2026

For AI agents: the whole contract is published as one machine-readable brief, /docs/agent.md (indexed in /llms.txt), with a build plan and acceptance tests; the one-line prompt in the widget on the right hands it to any coding agent.
balance_change carries round_end (true when no further movement follows for that round_id) — informational, not signed. Premium: false on the bet, true on the closing win/refund; standard games: always true.
Premium losing rounds now always close with a win of amount 0, as documented (it was skipped for wallets that reject a zero amount; see the rounds section for the fallback).
PG Soft, JILI, Endorphina, Fugaso, Gamzix, Amusnet and Iconic21 now send linked movements (bet / win / refund under one round_id, closed by round_end: true) instead of independent round movements — a PG Soft feature's free spins share the triggering spin's round_id.

v1.9 — Sep 2026

GET /api/v1/games and /games/{id} return title, the human-readable game name. name is the launch identifier and may be a slug — show title to players.
JILI titles now open from the API launch URL (they answered 400 INVALID REQUEST before).
language: Portuguese (pt) UI for Pragmatic, Hacksaw, Booming, Playtech, Blueprint, Evoplay, PG Soft, Amatic, Habanero, Fazi, Platipus and Bellink. Unsupported codes, and titles without a translation, fall back to en instead of breaking the load.

v1.8 — Sep 2026

balance_change carries game_id (the games-list id you launched) and provider_id (the provider slug) — informational, not signed. game + game_category alone were not a unique key.

v1.7 — Sep 2026

GET /api/v1/games and /games/{id} return game_type (slot | live | crash).
balance_change carries round_id and type (round | bet | win | refund) — informational, not signed.
Documented the retry policy (3× immediate, then hourly up to 12 attempts, same transaction_id) and added a reference wallet implementation in Node.js and PHP.

v1.6 — Jul 2026

Docs corrected to match the live /api/v1 contract (paths, request/response shapes, wallet models).
Catalog now exceeds 6,000 titles across 45+ providers (incl. Merkur, EGT Digital, Amatic, Novamatic, JILI, PG Soft, Nolimit City, ELK, Push Gaming).
Documented managed (deposit/withdraw) and seamless (user_data / balance_change) wallet models.

v1.5 — May 2026

Added PenguinKing / Octoplay and further premium (Reeltrix) providers.
Standard vs Premium catalog tiers exposed via ?type=.

v1.4 — May 2026

Added Gamzix and Hacksaw Gaming.
Player & balance management endpoints (/users/*, /balance/*).

v1.1 — Mar 2026

Added CrashGames and Tomhorn Gaming.
Demo-mode launches via the demo flag.

v1.0 — Jan 2026

Initial release: game catalog, HMAC-signed launch URLs, seamless wallet callbacks.

Need help? Contact support@bigbangcasino.bet or reach us on Telegram.