Operator API

These are the endpoints you must implement on your side. 155.io will call these endpoints to manage player balances and transactions.

Required Endpoints

Security Requirements

1. Verify incoming requests — every call from 155.io to your /balance, /bet, /win, or /rollback endpoint includes X-Marbles-Signature (RSA-SHA256 over the raw request body, BASE64-encoded). Use the 155.io public key shared at onboarding to verify.
2. Sign outgoing responses with your private key in the X-Marbles-Signature header. We don't currently verify your response signatures, but signing now is forward-compatible.
3. Whitelist 155.io outbound IPs at your firewall so our requests reach your endpoints.

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

Idempotency

All endpoints must be idempotent. If a request is executed multiple times, it should return the same response (even if the request ID differs).

If the same transactionId is received with a different payload, return DUPLICATE_TRANSACTION_ERROR.

Response Format

All responses must include:

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