How to Integrate a Casino Game Aggregator API: A Developer Guide

"Integrating a casino aggregator" sounds like it should be a single afternoon — and the README is always 90% there. This is the missing 10%: what shows up only after you take real-money traffic.

The four moving parts

1. Auth: API key only? Hope you used HMAC

Most aggregator docs say "send your API key in the X-API-Key header". That's fine for the catalog endpoint. For the RGS callback (when the aggregator calls YOU), you need HMAC-signed bodies — never trust an inbound call just because it has your key. The signing key is separate from your API key; if your docs don't mention it, ask before going live.

// Verifying an inbound RGS callback
const expected = crypto
  .createHmac('sha256', RGS_SIGNING_SECRET)
  .update(req.rawBody)
  .digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.header('X-Signature')))) {
  return res.status(401).json({ error: 'bad sig' });
}

2. Signed launch URLs — the clock gotcha

The aggregator hands you a URL with a TTL (usually 5–15 minutes). Your server signs it; the aggregator validates against the signature. If your server's NTP is drifting by more than ~30 seconds, signature validation will randomly fail on a fraction of launches. We've seen this kill 5–10% of game starts in production.

Fix: run chronyd or systemd-timesyncd; sample your clock drift via chronyc tracking at boot and alert if > 1s.

3. RGS callbacks: idempotency is the whole game

The aggregator will retry. Sometimes within seconds (network blip), sometimes minutes later (their queue backed up). If your /callback handler processes a bet twice, you've double-debited the player. If it processes a win twice, you've handed out free money.

The pattern that survives production:

// Pseudocode for an idempotent /callback handler
async function handleCallback(req) {
  const txId = req.body.transaction_id;        // ID from aggregator
  const cached = await redis.get(`tx:${txId}`);
  if (cached) return JSON.parse(cached);       // already handled

  const result = await db.transaction(async (t) => {
    // Apply balance change, record tx, atomically
    return await processBetOrWin(req.body, t);
  });

  await redis.set(`tx:${txId}`, JSON.stringify(result), 'EX', 86400);
  return result;
}

4. The currency conversion trap

If your players bet in BTC but the aggregator's pricing is in USD, someone is doing FX. Two things must be true:

• The rate used at bet time must equal the rate used at settle time for the same transaction.
• You must lock in the rate before calling the aggregator, not after.

Otherwise a single bet that takes 30 seconds (player thinking, then spinning) can clear at a different USD price than it was placed at, and the math doesn't balance.

5. Demo mode is not "no money"

Demo mode launches don't trigger RGS callbacks (no balance to move), but they DO trigger session events. If your analytics counts every game launch as "active player", demo traffic will inflate your DAU by 3–5x. Filter on the mode: 'real' flag in session events.

6. The 14 things to verify before going live

1. HMAC signature verification on all inbound callbacks
2. Idempotency keyed on transaction_id
3. Clock drift < 1s (NTP)
4. Currency locked per-transaction, not per-session
5. Demo mode flagged separately in analytics
6. Refund endpoint tested — most aggregators have it; most operators forget to implement it
7. Webhook deduplication (same event delivered 2+ times)
8. Rate-limit handling: 429 responses, exponential backoff
9. Graceful catalog reloads (provider adds/removes games without restarting your service)
10. Player-session timeout: what happens when player closes tab mid-spin?
11. Multi-currency player wallets if you support fiat + crypto
12. RGS callback timeout (must respond within ~3s to most aggregators)
13. Audit log: every state change to player balance, immutable
14. Reconciliation job: hourly compare your tx log vs aggregator's reported activity