Round History & Ledger Contract

For casino compliance and player transparency, the platform records every spin, hand, or round. The SDK exposes this data for "My Bets" / "Game History" pages.

Public surface

Member	Returns	Auth	Description
getRounds(payload?)	Promise<GameRound[]>	required	The player's round history, filtered and paginated

Round history is the player's own betting data; it requires an authenticated session.

Rounds ↔ wallet ledger contract

Every real-money round is mirrored into the wallet ledger exactly; this is the strict accounting link between the two modules. The stake is held at round start and settled at resolution, the same pattern withdrawals use:

GIVEN a REAL-mode round with betAmount B in currency C
WHEN the round STARTS
THEN the wallet's ledger in currency C gains one BET entry
     (DEBIT, amount B, status PENDING, reference = the round's id)
     and the stake is held; realBalance decreases by B.

GIVEN a PENDING round resolving as COMPLETED with winAmount W
WHEN the round resolves
THEN the BET entry's status flips PENDING → COMPLETED (append-only:
     only the status field ever transitions) and, if W > 0, one WIN entry
     (CREDIT, amount W, status COMPLETED, same reference) is written.

GIVEN a PENDING round resolving as FAILED
WHEN the round resolves
THEN the BET entry's status flips PENDING → FAILED and one REFUND entry
     (CREDIT, amount B, status COMPLETED, reference = the round's id)
     returns the stake.

GIVEN a PENDING round
WHEN it resolves server-side
THEN its status moves to COMPLETED or FAILED, the settlement entries above
     are written, and a GameRoundResolvedEvent fires on the
     [real-time channel](/realtime).

The round's reference field carries the provider's round ID (for support tickets); the wallet entries' reference carries the platform round id. See Transaction History for the ledger schema.

Typed structures

interface GameRound {
  id: string;             // platform round id; the ledger entries' reference
  gameId: string;
  gameName: string;       // denormalized for rendering
  provider: string;       // provider id
  betAmount: number;      // in `currency`
  winAmount: number;      // in `currency`; 0 if the round lost
  currency: string;
  status: 'COMPLETED' | 'PENDING' | 'FAILED';
  createdAt: string;      // ISO-8601
  reference?: string;     // the provider's internal round ID
}

interface GetRoundsPayload {
  limit?: number;   // default 20, max 100 (values above max are clamped)
  offset?: number; // default 0
  gameId?: string;  // filter to one game
}

Deterministic ordering: newest first; createdAt descending, then id as the stable tiebreaker, so pages are reproducible and no row is skipped or duplicated across pages.

const history = await sdk.games.getRounds({ limit: 20, offset: 0 });
const sweetBonanzaHistory = await sdk.games.getRounds({ gameId: 'game_sweet_bonanza', limit: 5 });

Round state machine

Status	Entry trigger	Allowed transitions	Side effects
PENDING	Round started, resolving at the provider	→ COMPLETED · → FAILED	BET entry (status PENDING) written; stake held
COMPLETED	Provider resolves the round	terminal	BET flips to COMPLETED; WIN written if winAmount > 0
FAILED	Provider rejects/voids the round	terminal	BET flips to FAILED; REFUND returns the stake

Rounds resolve server-side. Your UI learns about a resolution either from the GameRoundResolvedEvent (below) or by polling getRounds; polling always works.

Events

interface GameRoundResolvedEvent {
  eventId: string;   // dedupe key; see Real-Time Channel
  roundId: string;
  gameId: string;
  status: 'COMPLETED' | 'FAILED'; // discriminates the resolution
  winAmount: number;
  currency: string;
}

Fired on the shared real-time channel when a PENDING round resolves.

Error contract

Code	Error class	HTTP status	Trigger condition	Retryable
GAME_NOT_FOUND	GameNotFoundError	404	getRounds with an unknown gameId filter	No (fix the filter)

Common errors are defined once in the Error Reference.

Sandbox

6 seeded rounds across the three catalog games covering all statuses (4 COMPLETED, 1 PENDING, 1 FAILED). Rounds resolve through the sandbox controls:

await sdk.games.sandbox.completeRound('rnd_5', 12.5); // PENDING → COMPLETED (+WIN entry + event)
await sdk.games.sandbox.failRound('rnd_5');            // PENDING → FAILED (stake returned + event)

See Sandbox Controls.