Skip to content
LootBox Solutions

Quickstart

The shortest path to a box rendering in your page. Each step links to its full reference.

Prerequisites

  • A provisioned operator (https://{operator}.app.lootboxsolutions.com) and an API key (keyId + secret).
  • Your origin added to the allowed embedding origins.
  • A wallet endpoint — or pass a balanceMinor snapshot at launch to defer wiring it.

1. Sign a request

Every S2S call is HMAC-signed. The canonical string is:

canonical = "{timestamp}\n{METHOD}\n{path}\n{sha256(hex of body)}"
signature = hex(hmac_sha256(secret, canonical))

Send X-Key-Id, X-Timestamp, and X-Signature. Full details and a reference implementation: Authentication.

2. Mint a launch token

POST https://{operator}.app.lootboxsolutions.com/api/s2s/launches
X-Key-Id: igk_live_…
X-Timestamp: 1717420800
X-Signature: 9f86d0…


{
  "playerExternalId": "u_8431",
  "gameKey": "mystery_box",
  "target": { "boxId": 42 },
  "locale": "en",
  "currency": "EUR",
  "returnUrl": "https://casino.example/lobby"
}
{
  "launchToken": "lt_…",
  "launchUrl": "https://{operator}.app.lootboxsolutions.com/play?token=lt_…",
  "expiresAt": "2026-06-03T12:01:00Z"
}

Reference: Mint a launch token.

3. Embed the iframe

<iframe
  src="https://{operator}.app.lootboxsolutions.com/play?token=lt_…&parent=https://casino.example"
  allow="clipboard-write"
  style="width:100%;height:720px;border:0">
</iframe>

The game app exchanges the token, renders the box, and applies your branding. Reference: Embedding the iframe.

4. Handle messages from the iframe

window.addEventListener('message', (e) => {
  if (e.data?.source !== 'lootbox-solutions') return;
  switch (e.data.type) {
    case 'wallet:balance-changed': /* refresh your balance UI */ break;
    case 'play:auth-required':     /* prompt sign-in (guest mode) */ break;
  }
});

Reference: Host ↔ iframe messaging.

5. Answer the wallet call

When the player opens the box, LootBox Solutions POSTs wallet.debit to your wallet URL. Return { "accepted": true, "balanceAfterMinor": 11500 } to let the spin proceed, or { "accepted": false, "errorCode": "INSUFFICIENT_FUNDS" } to refuse. Reference: Operator configuration → wallet RPC.

Next steps

That’s the full loop — mint, embed, open, settle. Before launch, work through the Testing & sandbox checklist (mock wallet, idempotency, refusals), then explore embedding options and the Server-to-server API for backend-driven purchases.