Skip to content
The Aggregator

How a game round works

Every game round flows through three actors: your operator backend, The Aggregator, and the game provider. The player sees only the game iframe; you orchestrate the wallet.

The lifecycle

Section titled “The lifecycle”
sequenceDiagram
    participant Player
    participant Operator
    participant Aggregator
    participant Provider


    Player->>Operator: Opens game lobby
    Operator->>Aggregator: POST /v1/sessions (Idempotency-Key, game_id, player_id, balance, currency, country)
    Aggregator->>Provider: Create session
    Provider-->>Aggregator: Session URL
    Aggregator-->>Operator: { session_id, game_url }
    Operator->>Player: Redirect to game_url
    Player->>Provider: Plays the game
    Provider->>Aggregator: Bet callback (HMAC-signed)
    Aggregator->>Operator: POST /your-callback (bet)
    Operator-->>Aggregator: 200 OK (debited wallet)
    Provider->>Aggregator: Win callback (HMAC-signed)
    Aggregator->>Operator: POST /your-callback (win)
    Operator-->>Aggregator: 200 OK (credited wallet)
    Player->>Operator: Closes game

Step-by-step

Section titled “Step-by-step”

  1. Player opens your lobby. Your front-end calls your backend with the game they want to play.

  2. You create a session. POST /v1/sessions with an Idempotency-Key header and game_id, player_id, balance, currency, and country. The Aggregator returns session_id and game_url.

  3. You redirect the player. The game_url is a single-use signed URL. Embed it in an iframe or redirect the browser once — don’t cache or reload it.

  4. Provider sends bet callback. Each spin triggers an HMAC-signed callback to your configured callback_url. Verify the signature, debit the player’s wallet, return 200.

  5. Provider sends win callback. When the spin resolves with a payout, you receive a win callback. Credit the player’s wallet, return 200. A losing round closes as a zero-amount win, which is settled inside The Aggregator and not delivered to your wallet — nothing is owed, so there is nothing to credit. Those legs still appear in GET /v1/transactions with status: "completed"; do not expect a matching request in your own logs when reconciling.

  6. Player exits. The session stays open for replays. No explicit close call needed — sessions expire automatically.

Important constraints

Section titled “Important constraints”
  • game_url is single-use. Create the session immediately before redirecting the player; open it once and don’t cache, reload, or pre-fetch it.
  • Callbacks may arrive out-of-order under network jitter. The Aggregator does best-effort ordering but cannot guarantee strict sequence. Callback dedup by transaction_id is on you.
  • A session can have many bets and wins. Slot games typically generate one bet and one win per spin; live casino games can interleave them differently.
  • Failed callback (you return non-2xx) triggers retries with exponential backoff. See Wallet callbacks for retry semantics.
Section titled “Read next”