Skip to content
Bookmaker Docs

Overview

Bookmaker is a multi-tenant B2B sportsbook. You run your site, your player accounts and your cashier; we run the sportsbook (odds, markets, bet acceptance, settlement) and show it inside your pages in an iframe. Money never leaves your wallet: for every bet and every settlement our servers call yours.

Integration models

Section titled “Integration models”
Iframe + seamless wallet (this guide) Full white label
Players, login, KYC Yours. You tell us who the player is, server to server. Ours: registration, KYC, login with a second factor.
Balance and cashier Your wallet. We call debit, credit and rollback on it. Our ledger and PIX cashier.
Where the sportsbook lives An iframe in your pages (embed SDK). Its own domain with your brand.
What you build One session call, the iframe, four wallet endpoints. Nothing: configure domain and theme.

This guide covers the iframe model. For a full white label, talk to your account manager: it is configured, not integrated.

How it works

Section titled “How it works”
  1. Login. The player logs in on your site. Your server calls POST /api/v1/integration/sessions with your API key and gets back a launch token: single use, valid for 120 seconds.
  2. Launch. Your page mounts the sportsbook with the embed SDK and the launch token. The iframe exchanges it once for a session token that only lives inside the iframe, so long-lived tokens never appear in URLs, logs or Referer headers.
  3. Bet. When the player bets, we call POST {your walletUrl}/debit, signed with HMAC-SHA256. You answer with the new balance, or insufficient_funds.
  4. Settlement. When the market is resulted we call credit: the payout for a winning bet, the stake for a void bet, and a zero-amount credit for a lost bet, so every bet is closed in your books.
  5. Events. The iframe tells your page what happens through postMessage: balance_changed, bet_placed, bet_settled, login_required, deposit_requested and more, so your header and cashier stay in sync.
Integration sequenceThe operator's server creates the session with its API key and gives the page a launch token; the iframe exchanges it for a session; every bet debits the operator wallet and every settlement credits it, with a zero amount for lost bets.Operator pageplayer's browserOperator serveryour backendSportsbook iframeour originSportsbook APIserver to serverOperator walletyour /wallet endpoints1 Loginplayer logs in on your sitePOST /integration/sessions (X-API-Key)launchToken (single use, 120 s)launchToken2 Launch the iframemount({ launchToken }) or set_launch_tokenPOST /integration/launchsession token (memory only)ready · balance_changed3 BetPOST /betsPOST /debit kind=bet (HMAC){ txId, balance }bet accepted + balance pushbet_placed · balance_changed4 SettlementPOST /credit kind=payout (0 if lost){ txId, balance }push: bet settled, balancebet_settled · balance_changedHTTPS requestresponsepostMessage (SDK)signed wallet call
The operator's server creates the session with its API key and gives the page a launch token; the iframe exchanges it for a session; every bet debits the operator wallet and every settlement credits it, with a zero amount for lost bets.

What you build

Section titled “What you build”

In the back office

Allow your site’s origins to frame the sportsbook and set your theme (Embedding, Theming).

Conventions

Section titled “Conventions”
  • One origin serves the sportsbook (/), the API (/api/v1), the embed SDK (/embed/v1.js) and these docs (/docs/). Your account manager gives you the sandbox and production origins; locally it is http://localhost:8080.
  • JSON in and out. Every API call names the tenant with X-Tenant-ID.
  • Money is an integer number of minor units (cents): 1050 is $10.50 or R$ 10,50. Never floats.
  • Errors are {"error": {"code": "...", "message": "...", "details": {...}}}. Branch on code (and details.reason), never on message.
Quick startRun the sandbox and the reference operator, and see a bet hit your wallet.
PlaygroundMount the sandbox sportsbook and watch every event.