Operator API

The wallet API is four callbacks that 155.io sends to your wallet: /balance, /bet, /win, and /rollback. You implement these endpoints and respond; 155.io calls them to read balances and move money. This page states the rules that apply to all four — each callback page then covers only its own payload.

The four callbacks

/balance

Return the current balance of a player

/bet

/win

/rollback

Rollback a registered bet

Authentication

155.io signs every callback with the X-Marbles-Signature header (RSA-SHA256 over the raw request body, BASE64-encoded). Your endpoint verifies that signature against the 155.io public key shared at onboarding, and rejects requests that fail verification.

The direction is one-way: you never sign your responses, and 155.io does not verify them. Restricting inbound traffic — for example IP-whitelisting 155.io's outbound addresses at your firewall — is your own concern.

See Security for verification code samples and the full direction-aware picture.

Always respond HTTP 200

Always return HTTP 200

Every callback — success and error — must respond with HTTP 200. The outcome lives in the JSON body's status field. Returning a non-200 status, or a generic error body without a status, is the #1 integration mistake: it can trigger retries or rollbacks on our side.

{
  "status": "SUCCESS",
  "requestId": "original-request-id",
  "clientPlayerId": "player-id",
  "currency": "USD",
  "balance": 1000000
}

The full set of status values has a single canonical home in Error codes — refer there rather than memorising values from the callback pages.

Idempotency

Every money-moving callback must be idempotent: dedupe by transactionId. If the same transactionId arrives again, return the original result instead of moving money twice. Each callback page documents how this applies to its operation.

Amounts

All amount and balance fields are integers in the currency's minor units — there are no decimals on the wire. Precision is per-currency, so always look up the scale for the currency on the request. See Currencies for the precision table.

Treat `amount` as an exact integer — never round-trip it

Store, debit, and credit the amount exactly as the integer you receive. Do not convert it to a decimal/display value and back, and do not round it to fewer decimals than the currency's precision — that silently drops value and breaks balance reconciliation. (It's the single most common cause of failed acceptance checks: a high-precision currency like kIDR arrives as a large integer, the wallet round-trips it through a 2-decimal display value, and the debited amount no longer matches.) Precision is for displaying amounts to your players, not for your wallet's debit/credit math.

Implement the callbacks: /balance, /bet, /win, /rollback
Handle the Freebets & Rewards flow (free bets, reward grants)
Validate your integration with Acceptance testing
Validate your responses: Response simulator
Pull our games into your lobby: Get Games (POST /game/games)