Section 4

API reference

Every endpoint a game provider may call. Wallet routes return raw bodies; everything under /api/v1/ returns the envelope. All paths are relative to {RELAY_BASE_URL}, and all require the game provider token unless stated.

Wallet: account, cash-out, cash-in, cash-in retry, round-ended
Sessions: validate
Configuration: casino ids, casino catalog
Reporting: rounds, round detail, transactions, transaction detail
Operational: health

Wallet routes (raw body)

Success is 200 with the account object. Any failure is { "error": "CODE" } with the status listed under each route. Codes shared by every session-scoped wallet route:

Status	Codes
400	`Bad Request` (validation), `SESSION_GAME_MISMATCH`, `SESSION_CURRENCY_MISMATCH`
403	`AUTHENTICATION_FAILED`, `GROUP_NOT_ACTIVE`, `SESSION_EXPIRED`, `GAME_NOT_OWNED_BY_GROUP`, `GAME_NOT_ACTIVE`, `PROVIDER_NOT_ACTIVE`, `AUTHENTICATION_TOKEN_EXPIRED`
404	`GAME_NOT_FOUND`, `PROVIDER_NOT_FOUND`
408	`INTEGRATION_TIMED_OUT`
502	`PROVIDER_API_FAILURE`, `INVALID_PROVIDER_RESPONSE`

The account object

{
  "id": "48213",
  "balance": 240.00,
  "username": "lucky_sam"
}

id: The casino's player identifier. Matches playerId on the session.
balance: Player balance after the operation, in the session currency, rounded to two decimals.
username: Display name from the casino. May equal id when the casino has none.

Account (balance)

GET/api/account

Current balance and identity. Relayed to the casino on every call; nothing is cached.

Query parameters

sessionIdrequired: The session from the launch redirect.
currencyoptional: Checked against the session when present.

GET /api/account?sessionId=6f1e0d5c-…&currency=USD
200
{
  "id": "48213",
  "balance": 250.00,
  "username": "lucky_sam"
}

Cash-out (bet)

POST/api/balance/cash-out

Debit the player (the bet) and open the round.

Body

sessionIdrequired: Player session.
gameIdrequired: Integer. Must equal the session's game.
currencyrequired: Must equal the session's currency (case-insensitive).
roundIdrequired: Game-generated identifier of the bet's round. Unique per casino.
transactionIdrequired: Game-generated identifier of the debit. Unique per casino. Idempotency key.
amountrequired: Stake. Number, non-negative, at most 2 decimals.
languageoptional: Overrides the session language for this call.
gameoptional: Object with optional gameData and meta objects. Stored on the round, never forwarded to the casino, never interpreted.

Additional error codes

400	`FUND_WITHDRAW_FAILED`	Casino refused the debit (insufficient funds).
409	`TRANSACTION_IN_FLIGHT`	Same `transactionId` still being processed.
500	`CASHOUT_FAILED`	Casino failed the debit with a server error.

POST /api/balance/cash-out
{
  "sessionId": "6f1e0d5c-…",
  "gameId": 101,
  "currency": "USD",
  "roundId": "r-000871-48213",
  "transactionId": "bet-01J8Z1Q9K4X2Y7",
  "amount": 10.00,
  "game": {
    "gameData": {
      "grid": 25,
      "mines": 3
    }
  }
}

200
{
  "id": "48213",
  "balance": 240.00,
  "username": "lucky_sam"
}

Cash-in (settlement)

POST/api/balance/cash-in

Credit the player (win, refund, or zero-amount loss) and settle the round.

Body

sessionId, gameId, currency, roundId, transactionId, amount, language: As on cash-out. transactionId is a new id for this credit.
reasonrequired: One of the cash-in reasons. Any other value is a 400.
appliedMultiplierrequired: Number ≥ 0. The multiplier for NORMAL_WIN / FREEBET_WIN; 0 for every other reason.
previousTransactionIdoptional: The bet's transactionId. Send it for every reason that settles a bet.
betAmountoptional: Original stake, at most 2 decimals. Defaults to 0; always send it.
awardIdoptional: Freebet identifier. With FREEBET_WIN and FREEBET_LOST.
campaignIdoptional: Freebet campaign identifier.
isLastFreebetoptional: Boolean. True when this was the player's last freebet.
gameoptional: Object with optional outcome (string), settlementData and meta objects. Stored on the round, never forwarded, never interpreted.

Additional error codes

409 TRANSACTION_IN_FLIGHT Same transactionId still being processed.

POST /api/balance/cash-in
{
  "sessionId": "6f1e0d5c-…",
  "gameId": 101,
  "currency": "USD",
  "roundId": "r-000871-48213",
  "transactionId": "win-01J8Z1S2M7P0Q3",
  "previousTransactionId": "bet-01J8Z1Q9K4X2Y7",
  "reason": "NORMAL_WIN",
  "amount": 24.50,
  "betAmount": 10.00,
  "appliedMultiplier": 2.45,
  "game": {
    "outcome": "CASHED_OUT",
    "settlementData": {
      "revealed": [
        3,
        7,
        12
      ]
    }
  }
}

200
{
  "id": "48213",
  "balance": 264.50,
  "username": "lucky_sam"
}

Cash-in retry

POST/api/balance/cash-in/retry

Retry a credit that failed earlier. Identical body to cash-in, including sessionId; no extra header. The relay may resolve a session that has already expired from its live store by falling back to its archive (kept for two months), so delayed credits still reach the player. Same error codes as cash-in.

Round-ended

POST/api/round-ended

Notify one or more casinos that a game round has ended. No money moves and no session is involved.

Body

roundIdrequired: The round that ended.
providerIdsrequired: Non-empty array of casino ids. Duplicates are notified once.

Error codes

400	`Bad Request`	Validation failed.
403	`AUTHENTICATION_FAILED`, `PROVIDER_NOT_ACTIVE`, `AUTHENTICATION_TOKEN_EXPIRED`	Token rejected, a named casino is inactive, or a casino rejected the notification.
404	`PROVIDER_NOT_FOUND`	A named casino id does not exist. Nobody was notified.
408 / 502	`INTEGRATION_TIMED_OUT`, `PROVIDER_API_FAILURE`	A casino did not answer properly. Other casinos in the list were still notified.

POST /api/round-ended
{
  "roundId": "r-000871",
  "providerIds": [
    "66ffba1337e994c3009ebf40"
  ]
}

200
{
  "ok": true
}

Sessions (envelope)

Validate session

GET/api/v1/sessions/{sessionId}

Validates the session for the calling game provider and confirms it with a live balance call to the casino. Details and the full error table are on the launch page.

Query parameters

gameIdrequired: The game the session is expected to belong to.
currencyoptional: Compared case-insensitively.

GET /api/v1/sessions/6f1e0d5c-…?gameId=101
200
{
"statusCode": 200,
"message": "Session is valid",
"data": {
  "valid": true,
  "sessionId": "6f1e0d5c-…",
  "gameId": 101,
  "gameName": "Mines",
  "groupId": "66ffc0a1…",
  "providerId": "66ffba13…",
  "playerId": "48213",
  "currency": "USD",
  "language": "en",
  "expiresAt": "2026-09-22T09:14:03.000Z"
}
    }

Configuration (envelope)

Casino ids

GET/api/v1/providers/ids

Every casino's id and registration date, newest first. Not paginated. This is the only casino endpoint available to a game provider; names and connection details are not exposed here.

daysoptional: Integer 1 to 30. Only casinos registered in the last N days. Above 30 is a 400.

GET /api/v1/providers/ids?days=7
200
{
"statusCode": 200,
"message": "Provider ids fetched successfully",
"data": [
  {
    "providerId": "66ffba1337e994c3009ebf40",
    "createdAt": "2026-07-24T11:19:26.294Z"
}
      ]
    }

Casino catalog

GET/api/v1/provider-catalog

For the calling game provider's games, what each casino has configured: per-game settings and per-currency bet limits. Grouped casino → game. Not paginated; sorted by casino registration date, newest first. The structure is described in Casino configuration.

gameIdoptional: Narrow to one of the game provider's games. A game owned by another game provider gives an empty result.
providerIdoptional: Narrow to one casino.

Reporting (envelope, paginated)

A game provider token sees only its own game provider's data. Lists share these parameters:

page, limit: 1-based page and page size. Default 1 and 20, maximum limit is 100.
from, to: ISO-8601 dates; inclusive range on creation time.
sortBy, sortOrder: sortOrder is asc or desc (default). Sortable fields are listed per route.
gameId, providerId, playerId, roundId, currency: Exact-match filters.

List rounds

GET/api/v1/rounds

Extra filters: status (OPEN or SETTLED). Sortable by createdAt, openedAt, settledAt, betAmount, payoutAmount.

Round detail

GET/api/v1/rounds/{providerId}/{roundId}

One round plus its transactions. Both path segments are required because round ids are unique per casino.

List transactions

GET/api/v1/transactions

Extra filters: transactionId, category (CASH_OUT or CASH_IN), status (PENDING, SUCCESS, FAILED). Sortable by createdAt, completedAt, amount.

Transaction detail

GET/api/v1/transactions/{providerId}/{transactionId}

One transaction. Field descriptions and examples are on the Reporting page.

Operational

Health and readiness

GET/api/healthz · GET/api/readyz

No authentication. healthz says the process is up; readyz says its dependencies are reachable. Intended for uptime monitoring, not for game logic.

Wallet routes (raw body)​

The account object​

Account (balance)​

Query parameters​

Cash-out (bet)​

Body​

Additional error codes​

Cash-in (settlement)​

Body​

Additional error codes​

Cash-in retry​

Round-ended​

Body​

Error codes​

Sessions (envelope)​

Validate session​

Query parameters​

Configuration (envelope)​

Casino ids​

Casino catalog​

Reporting (envelope, paginated)​

List rounds​

Round detail​

List transactions​

Transaction detail​

Operational​

Health and readiness​

Wallet routes (raw body)

The account object

Account (balance)

Query parameters

Cash-out (bet)

Body

Additional error codes

Cash-in (settlement)

Body

Additional error codes

Cash-in retry

Round-ended

Body

Error codes

Sessions (envelope)

Validate session

Query parameters

Configuration (envelope)

Casino ids

Casino catalog

Reporting (envelope, paginated)

List rounds

Round detail

List transactions

Transaction detail

Operational

Health and readiness