OrbiPoker developer documentation · API v1

Real-money poker inside your casino, with one URL and one webhook.

OrbiPoker runs the whole poker room: game engine, lobby, cash tables, fast-fold, Sit & Go, Spin & Go and tournaments, back office and integrity. You keep the player account, KYC and money. The game opens in an iframe on your site, and every chip movement is a signed call to your wallet.

Architecture

• Money stays with you. OrbiPoker never holds balances. Chips on a table or a tournament entry exist because your wallet accepted a debit.
• Integer minor units. Every amount is an integer in the currency's smallest unit (cents). Tournament chips are plain integers and never touch the wallet.
• Network or private. Your players can share tables with other operators (network liquidity) or only meet each other (private). This is a per-operator setting.
• Three languages. The game client speaks pt-BR, en and es.

Quick start

From zero to a hand dealt on your staging site. OrbiPoker staff create your operator account and send you an API key (orbp_sk_…) and a wallet secret (whsec_…) once.

1. Try the sandbox. Open /sandbox: it acts as an operator backend for the demo tenant, so you can see launches, iframe events and wallet calls without writing code.
2. Run the reference wallet. Download wallet-receiver.mjs (Node 24, no dependencies) and run it with your secret. Expose it over HTTPS.
3. Configure the back office. In /backoffice set the wallet URL, add the origins that will embed the iframe and press “Test wallet”.
4. Create a launch and embed it. Call POST /api/v1/launch from your server and mount the returned URL with the SDK.
5. Play a hand. Sit at a table: your wallet receives a debit. Leave: it receives a credit.

# 1. the reference wallet (keep the secret out of shell history in production)
ORBIPOKER_WALLET_SECRET=whsec_… PORT=3001 START_BALANCE=100000 node wallet-receiver.mjs

# 2. a launch for player 42
curl -X POST "$ORBIPOKER_URL/api/v1/launch" \
  -H "Authorization: Bearer $ORBIPOKER_API_KEY" -H "Content-Type: application/json" \
  -d '{"playerId":"42","currency":"BRL","locale":"pt-BR","parentOrigin":"https://staging.casino.example"}'

Authentication

Server-to-server calls use an operator API key in the Authorization header. Keys start with orbp_sk_, are shown once when created, are stored only as a SHA-256 hash, and can be created and revoked in the back office (Integration → API keys). Never send a key to a browser or an app.

Authorization: Bearer orbp_sk_9xQ…

Errors are JSON: {"error":"human message","code":"MACHINE_CODE"}, sometimes with extra fields such as min and max. Branch on code, never on the message. Every API call is written to the audit log with method, path and duration.

The wallet webhook works the other way round: OrbiPoker calls you and signs each request with your wallet secret. See Seamless wallet.

Launch API

Call this from your backend each time a logged-in player opens poker. It creates (or updates) the player and returns a single-use URL for the iframe.

POST /api/v1/launch
Authorization: Bearer orbp_sk_…
Idempotency-Key: open-poker-42-1792443000
Content-Type: application/json

{
  "playerId": "42",
  "nickname": "AnaRiver",
  "currency": "BRL",
  "locale": "pt-BR",
  "country": "BR",
  "parentOrigin": "https://casino.example",
  "sessionToken": "your-session-reference",
  "lobby": "spin",
  "depositUrl": "https://casino.example/cashier",
  "exitUrl": "https://casino.example/casino"
}

201 Created
{ "launchId": "lc_3f…", "launchUrl": "https://…/launch/lc_3f….Gx2…", "expiresAt": 1792443120000 }

Rules

• Single use, 120 seconds. The URL expires two minutes after creation and is consumed when the iframe loads it. Create a new launch every time the player opens poker; never cache or share launch URLs.
• Player session. Consuming the URL issues a player token valid for 12 hours. Reloading the iframe keeps the session; when it expires the client emits orbipoker:session-expired and you create a new launch.
• Idempotency-Key. Optional, 8–100 characters of [A-Za-z0-9_-]. Repeating the call with the same key returns the same launch; the same key with a different playerId fails with 409 IDEMPOTENCY_CONFLICT.
• Origins. parentOrigin must exactly match one of your allow-listed origins (HTTPS, no path; plain HTTP only for localhost), otherwise 403 ORIGIN_NOT_ALLOWED.
• Framing (CSP). /launch/<code> is served with Content-Security-Policy: frame-ancestors 'self' <your allow-listed origins>, so browsers refuse to render it anywhere else. Sandbox accounts allow any origin.
• Blocked players. A blocked or self-excluded player gets 403 PLAYER_BLOCKED until the block ends.
• Strict body. Unknown fields are rejected with 400 INVALID_BODY, so typos fail loudly.

Iframe and SDK

Put the launch URL in an iframe. The SDK does it for you and turns the client's postMessage events into callbacks.

With the SDK (recommended)

<div id="poker"></div>
<script src="https://<orbipoker-host>/sdk/v1/orbipoker.js"></script>
<script>
  const poker = OrbiPoker.mount({
    container: '#poker',                 // selector or element
    launchUrl,                            // from POST /api/v1/launch
    onReady:   info => console.log(info.playerId, info.locale),
    onBalance: ({balance, currency}) => header.setBalance(balance, currency),
    onDeposit: () => cashier.open(),
    onExit:    () => location.assign('/casino'),
    onSessionExpired: () => relaunch(),   // create a new launch
    onError:   ({code, message}) => log(code, message),
    onEvent:   event => analytics.track(event.type, event)
  });
  poker.refreshBalance();   // after a deposit in your cashier
  poker.setLocale('es');     // pt-BR | en | es
  poker.destroy();          // removes the iframe and listeners
</script>

• Load the SDK from the OrbiPoker host. It only accepts launch URLs from the same origin it was served from, and only trusts messages whose origin and source are that iframe.
• The iframe height follows orbipoker:resize (320–20,000 px) unless you pass height (number of px or any CSS length). Default height is 720 px.
• mount() returns {iframe, refreshBalance(), setLocale(locale), destroy()}. It throws if the container is missing or the launch URL is not an OrbiPoker /launch/ URL.

Plain iframe

<iframe src="{launchUrl}" title="Poker" allow="autoplay; fullscreen; clipboard-write"
        style="border:0;width:100%;height:720px"></iframe>
<script>
  const ORBIPOKER = 'https://<orbipoker-host>', frame = document.querySelector('iframe');
  addEventListener('message', e => {
    if (e.origin !== ORBIPOKER || e.source !== frame.contentWindow) return;
    const m = e.data;
    if (m?.source !== 'orbipoker' || m.version !== 1) return;
    if (m.type === 'orbipoker:resize') frame.style.height = m.height + 'px';
  });
  // host → iframe
  frame.contentWindow.postMessage({source: 'orbipoker-host', version: 1, type: 'orbipoker:refresh-balance'}, ORBIPOKER);
</script>

Events (iframe → host)

Every message is {source: 'orbipoker', version: 1, type, …fields}, posted only to your parentOrigin (to * only in the public demo).

Messages (host → iframe)

{source: 'orbipoker-host', version: 1, type} with type = orbipoker:refresh-balance (re-read the wallet balance) or orbipoker:locale plus locale. Always target the OrbiPoker origin, never *.

Seamless wallet

You implement one HTTPS endpoint. OrbiPoker calls it to read the balance, to take money when chips are bought (debit), to return money when chips come back (credit) and to undo a debit whose outcome is unknown (rollback).

Request

POST https://wallet.casino.example/orbipoker
Content-Type: application/json
User-Agent: OrbiPoker-Wallet/1
X-OrbiPoker-Signature: t=1792443000,v1=5105527f40f453f1716c2efc94ad7f9c7498186b546bf6c0924dcbde3b3dab50

{"version":1,"event":"debit","transactionId":"0d3c2f9e-8a1b-4c7e-9f1a-2b6d5e4c3a10","referenceTransactionId":null,
 "tenantId":"7b1e…","playerId":"42","currency":"BRL","amount":5000,"reason":"cash_buyin",
 "tableId":"t_9f…","tournamentId":null,"handId":null,"sessionToken":"your-session-reference","createdAt":1792443000123}

200 OK
{"balance": 120000}

Signature

X-OrbiPoker-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>. Compute the HMAC over the raw bytes you received, before any JSON parsing, compare in constant time, and reject timestamps more than 300 seconds from your clock. Answer 401 on failure. Rotate the secret in the back office; the new secret applies immediately.

import {createHmac, timingSafeEqual} from 'node:crypto';

export function verifyOrbiPoker(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(String(header || '').split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 || '')) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, 'hex'));
}
// Express: app.post('/orbipoker', express.raw({type: 'application/json'}), (req, res) => …)
// verifyOrbiPoker(req.body.toString('utf8'), req.get('X-OrbiPoker-Signature'), process.env.ORBIPOKER_WALLET_SECRET)

function verify_orbipoker(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        [$k, $v] = array_pad(explode('=', $pair, 2), 2, '');
        $parts[trim($k)] = trim($v);
    }
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) return false;
    if (abs(time() - (int) $parts['t']) > $tolerance) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

$raw = file_get_contents('php://input');   // raw body, before json_decode
if (!verify_orbipoker($raw, $_SERVER['HTTP_X_ORBIPOKER_SIGNATURE'] ?? '', getenv('ORBIPOKER_WALLET_SECRET'))) {
    http_response_code(401); exit;
}

import hmac, hashlib, time

def verify_orbipoker(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(',') if '=' in p)
    t, v1 = parts.get('t', ''), parts.get('v1', '')
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

# Flask: verify_orbipoker(request.get_data(), request.headers.get('X-OrbiPoker-Signature', ''), SECRET)

Responses

Idempotency

• Deduplicate by transactionId in the same database transaction as the balance change. A retry carries a byte-identical body.
• A duplicate gets the same outcome as the original: 2xx with the current balance if it was applied, the same decline if it was declined. Never apply it twice.
• Store a hash of the raw body. The same transactionId with a different body is a bug or an attack: answer 409 and alert.
• Process deliveries for one player serially (row lock or BEGIN IMMEDIATE); credits and rollbacks may arrive concurrently with a new debit.

Rollback semantics

OrbiPoker sends a rollback immediately when a debit times out (8 s) or fails at the network level, because it cannot know whether you applied it. The player is told nothing was charged. referenceTransactionId is the debit's transactionId, amount is the debit amount and reason is debit_timeout.

1. Debit applied: restore exactly the debited amount once, mark the debit as rolled back, answer 2xx.
2. Debit never seen (the rollback overtook it, or it never arrived): store a tombstone for referenceTransactionId and answer 2xx without moving money.
3. Debit arrives after its tombstone: refuse it with a non-2xx status (for example 409). Money must not move.
4. Debit already rolled back or declined: answer 2xx and change nothing.

Delivery, timeouts and retries

• Timeout: 8 seconds per attempt. Redirects are not followed. The response body is read up to 16 KB.
• Every movement is written to OrbiPoker's database (outbox) before it is sent, so nothing is lost on a restart.
• Credits and rollbacks: first attempt immediately, then exponential backoff of 2 s × 2^attempt capped at 30 minutes (2 s, 4 s, 8 s … 17 min, 30 min, 30 min …) for 24 hours. After that the transaction is marked failed and shows in the back office for manual reconciliation (POST /api/v1/transactions/{id}/retry resends the same body).
• Debits are synchronous and never retried: the player waits for your answer before sitting down.
• The wallet URL must be HTTPS and resolve to a public address; private and loopback addresses are refused (sandbox accounts excepted).

When money moves

Minor units follow the currency's decimals: 2 for USD, EUR, BRL, GBP, MXN, ARS, PEN, CAD, USDT, INR, PHP and CR; 0 for CLP and COP. 5000 BRL is R$ 50,00; 5000 CLP is CLP$ 5.000.

The reference receiver implements all of the above in about 140 lines of dependency-free Node (node:http + node:sqlite), and the repository's test suite checks it against the real signer.

Operator REST API

Every endpoint below takes Authorization: Bearer orbp_sk_…, speaks JSON and is scoped to your operator. This table is generated live from /openapi.json (OpenAPI 3.1), which is the source of truth for request schemas.

Notes

• GET /api/v1/players/{playerId} accepts your playerId and returns status, limits, lifetime stats, recent hands, tournaments, wallet movements and inPlay (chips currently on tables and active tournament entries).
• POST /api/v1/tables creates a private table for your players, or a shared one with "network": true if your liquidity is network. Fields: name (2–40), kind (cash | fastfold), variant, currency, bb, optional sb (default bb/2), ante, bbAnte, seats (2, 6, 8, 9; Short Deck, PLO5 and PLO6 up to 6), minBuyIn/maxBuyIn (default 40/100 BB, allowed 10–1,000 BB), rakeBps, rakeCap (absolute, minor units) and features (straddle, runItTwice, rabbitHunt, anonymous).
• POST /api/v1/tournaments creates an MTT (one-off unless template: true with recurringMinutes) or a Sit & Go / Spin template that keeps one instance open at all times. See Games and rules for defaults. DELETE cancels a tournament that has not started (everyone is refunded) or archives a template (tt_…).
• GET /api/v1/hands/{handId}?format=text returns a PokerStars-style hand history. Operator hand views include every hole card, for integrity reviews.
• Timestamps are Unix milliseconds. List endpoints take limit (max 500) and, where noted, offset.

Configuration

Read with GET /api/v1/config, change with PATCH /api/v1/config (deep-merged) or in the back office. Validation is strict: unknown top-level keys, unknown colours or features, fonts outside the list and out-of-range numbers are rejected with 400. No raw CSS ever reaches the client.

PATCH /api/v1/config
{ "theme": { "preset": "classic", "font": "Montserrat" },
  "timers": { "actionSeconds": 20 },
  "features": { "spins": true, "hud": false },
  "rake": { "bps": 450 } }

Games and rules

Defaults follow PokerStars and GGPoker, so regular players feel at home. The reasoning behind each default, with the market research, is in docs/FEATURES.md in the repository.

Variants

Rake

Cash and fast-fold hands pay rake.bps of the pot, floored to the minor unit and capped by the number of players dealt in: by default 1 BB heads-up, 2 BB with 3–4 players and 3 BB with 5 or more. With no flop, no drop. Tournaments pay no rake: the fee is charged at registration. Rake is attributed to each player in proportion to what they put in the pot (contributed method); that is what per-player and per-operator reports use.

Table rules

• Timers and time bank. When the action clock runs out the time bank starts automatically. When both run out the player checks if possible, otherwise folds and is sat out. The bank grows by timeBankRefillSeconds every timeBankRefillHands hands up to timeBankMaxSeconds.
• Run it twice. Cash tables only (not fast-fold or tournaments). When everyone is all-in before the river and every all-in player keeps the option on (default on), two boards are dealt and each pot is split between them.
• Straddle. When the table allows it, the player under the gun can opt in to post 2 BB blind (3+ players, cash only). Action starts left of the straddle.
• Antes. Cash tables may have a classic ante (everyone) or a big-blind ante (one ante of 1 BB from the big blind). Blinds take priority when a stack cannot cover both.
• Wait for big blind. A player joining a running table is dealt in when the big blind reaches them.
• Rathole protection. Returning to the same table within 30 minutes requires at least the stack you left with (up to 3 × the max buy-in).
• Sit-out and busts. Sitting out longer than sitOutKickMinutes cashes the player out. A busted player has 2 minutes to top up.
• Same network. Two players on the same IP address cannot sit at the same cash table (SAME_NETWORK); the attempt raises an integrity alert.
• Rabbit hunt and equity. After an uncontested pot the undealt board is shown for free. All-in equity is shown when players are all-in before the river.
• Fast-fold. Players join a pool and are dealt a new table every hand. Folding works before your turn. The big blind goes to whoever has gone longest without posting it; seats are shuffled; pools are anonymous by default.

Tournaments

• Speeds: slow 15 min, regular 10 min, turbo 5 min, hyper 3 min per level (override with levelSeconds, 60–3,600). Blinds climb a fixed ladder of 1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10… × the starting big blind.
• MTT registration: late registration for lateRegLevels levels (default 8), closing early if 15% or fewer entrants remain. Re-entry up to maxEntries (1–10) while late registration is open. If fewer than minPlayers are registered at startAt, the tournament is cancelled and refunded. Tables are balanced and broken between hands.
• Payouts: Sit & Go pays 100% up to 3 seats, 65/35 up to 6 and 50/30/20 above. MTTs pay about 15% of entries on a decreasing curve with a min-cash of at least 1.5 buy-ins, fixed when late registration closes. Players who bust during late registration finish out of the money. If the pool is smaller than the guarantee, the guarantee is paid.
• PKO: each entry carries a bounty. Knocking a player out wins their bounty: half in cash right away (tourney_bounty), half added to your own bounty (set progressiveBounty: false for a regular knockout). The winner also collects their own bounty.
• Crash policy: stacks are saved after every hand. If the server restarts during a tournament, the remaining prize pool (or the guarantee) is split by chip count, each player gets their current bounty, and the tournament is closed. Cash tables return the stack from the last completed hand.

Spin & Go multipliers

The multiplier is drawn when the Spin fills. The prize pool is multiplier × buy-in. The expected multiplier is 3 × (1 − fee), so RTP is 93.0% on the 7% table (GGPoker Spin & Gold) and 92.0% on the 8% table (PokerStars Spin & Go).

Provably fair shuffle

1. Before each hand the server draws a 32-byte serverSeed from the operating system's CSPRNG and publishes commitment = SHA-256(serverSeed bytes) in the table view.
2. The deck (52 cards, or 36 for Short Deck, ordered 2c 2d 2h 2s 3c … As) is shuffled with Fisher-Yates from the last position down. Random numbers are the big-endian 32-bit words of HMAC-SHA256(key = serverSeed, message = handId + ":" + counter) for counter = 0, 1, 2…; a word is rejected and the next one used when it is ≥ ⌊2³²/range⌋ × range, so every permutation is equally likely.
3. Cards are dealt from the top of the shuffled deck with no burn cards: hole cards one at a time to each player starting with the button seat, then flop, turn and river (and a second board when running it twice).
4. When the hand ends, serverSeed is revealed in the result, the hand history and the API, so anyone can rebuild the deck.

// Runs in any modern browser or Node ≥ 20 (WebCrypto).
async function verifyHand({serverSeed, commitment, handId, deck, shortDeck = false}) {
  const hex = buf => [...new Uint8Array(buf)].map(b => b.toString(16).padStart(2, '0')).join('');
  const seed = Uint8Array.from(serverSeed.match(/../g), h => parseInt(h, 16));
  if (hex(await crypto.subtle.digest('SHA-256', seed)) !== commitment) return false;
  const key = await crypto.subtle.importKey('raw', seed, {name: 'HMAC', hash: 'SHA-256'}, false, ['sign']);
  let counter = 0, words = [];
  async function next() {
    if (!words.length) {
      const block = new DataView(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(handId + ':' + counter++)));
      for (let i = 0; i < 32; i += 4) words.push(block.getUint32(i));
    }
    return words.shift();
  }
  const cards = [];
  for (let c = 0; c < 52; c++) if (!shortDeck || (c >> 2) >= 4) cards.push(c);   // rank = c >> 2, suit = c & 3
  for (let i = cards.length - 1; i > 0; i--) {
    const range = i + 1, limit = Math.floor(2 ** 32 / range) * range;
    let value; do value = await next(); while (value >= limit);
    const j = value % range; [cards[i], cards[j]] = [cards[j], cards[i]];
  }
  const name = c => '23456789TJQKA'[c >> 2] + 'cdhs'[c & 3];
  return cards.map(name).join(' ') === deck.join(' ');   // deck from the "verify" message
}

Players get commitment, serverSeed and the full deck from the client's hand history (“Verify”). Operators get commitment and serverSeed from GET /api/v1/hands/{handId}.

Responsible gaming

You own the player relationship, so you drive these controls from your own tools. All of them are audited.

Reports and settlement

The back office shows the same data as the API and exports CSV. Amounts are minor units of each row's currency.

• GET /api/v1/reports/ggr?from&to&groupBy=day|total — one row per day (UTC) and currency. Default range: the last 30 days.
• GET /api/v1/reports/players?from&to — per player: hands, rake, cashNet, tournamentFees, tournamentEntries. Use it for rakeback, loyalty and affiliate payouts. Default range: the last 7 days.
• GET /api/v1/transactions?status= — every wallet movement with its delivery status, attempts, last error and the balance you returned. Reconcile it against your wallet ledger by transactionId.
• GET /api/v1/hands and /hands/{id} — hand search and full hands (JSON or text) for support and integrity reviews. Integrity alerts (same network, chip dumping, bot-like timing) are listed in the back office.

Sandbox

• /demo opens the game as an anonymous demo player of the built-in demo operator (network liquidity, USD and BRL).
• /sandbox plays the operator: it creates launches for a player id you choose, embeds them with the SDK and shows the events. It mirrors POST /api/v1/launch.
• The demo operator's wallet is a built-in receiver that speaks the exact contract described above over real HTTP, signatures, idempotency, rollbacks and tombstones included. Every demo player starts with 1,000,000 minor units (10,000.00).
• Demo tables are kept busy by practice bots named “Bot…”. Bots only ever join tables, pools and tournaments of sandbox operators; real-money operators never see them.
• Your own sandbox operator (ask OrbiPoker) may use an HTTP wallet URL and any embedding origin, so you can point it at a local tunnel running the reference receiver.

Go-live checklist

• API key stored in your secret manager, used only server-side; a second key ready for rotation.
• Launch created per poker open, never cached; parentOrigin set; sessionToken passed if you want to tie movements to sessions.
• All production origins (including www and app web views) in the allow-list.
• Wallet URL on HTTPS with a public certificate; responds in well under 8 s at peak.
• Signature verified over the raw body with a 300 s tolerance; bad signatures get 401.
• Idempotency by transactionId inside the balance transaction; duplicates return the original outcome; body-hash conflicts return 409.
• Rollbacks restore the debit once; unknown references create a tombstone; a debit arriving after its tombstone is refused.
• No code path returns non-2xx after a debit was applied.
• Monitoring on retrying, failed and unknown transactions; a daily reconciliation of /api/v1/transactions against your ledger.
• Responsible-gaming tools wired to block, limits and kick; self-exclusion tested end to end.
• Theme, logo, locales and enabled formats reviewed on a phone; Deposit and Exit buttons wired through the SDK.
• Liquidity choice (network or private), currencies and revenue share agreed with OrbiPoker. RNG certification status checked for your jurisdictions.

AI agents

Using an AI coding agent for the integration? Point it at these plain-text sources; they need no JavaScript or login.

• /llms.txt — index of machine-readable sources.
• /integration-agent.md — step-by-step integration guide with acceptance tests.
• /openapi.json — OpenAPI 3.1 for the operator API and the wallet webhook.
• /wallet-receiver.mjs — reference wallet receiver.

Changelog

1.0.0 · 2026-10-19

First public version: launch API, iframe client and SDK v1, seamless wallet v1 (balance, debit, credit, rollback), operator REST API, cash tables, fast-fold, Sit & Go, Spin & Go, MTT with PKO, back office, provably fair shuffle. Added during the release: Cash Drops (promotions.cashDrop, promoCost), GET /api/v1/reports/players, inPlay on player profiles and the sessionMinutes limit.

Wallet payloads carry version. New optional fields may be added at any time; ignore fields you do not know. Breaking changes get a new version and advance notice.