Operator API
Endpoints you must implement for 155.io integration
These are the endpoints you must implement on your side. 155.io will call these endpoints to manage player balances and transactions.
Required Endpoints
/balance
Return the current balance of a player
/bet
Register a bet the player made
/rollback
Rollback a registered bet
/win
Register a win or loss
Security Requirements
Required
Your API must validate all incoming requests and sign all outgoing responses.
- Validate incoming requests using the
X-Marbles-Signatureheader - Sign outgoing responses with your private key in the
X-Marbles-Signatureheader
See Security for implementation details.
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
}Balance and amount values use 5-digit precision: $10.00 = 1000000. All amount and balance fields are 64-bit integers (int64 / long).
All responses must use HTTP 200, including error responses. The error status is communicated in the JSON body's status field. Non-200 HTTP status codes may trigger retries or rollbacks on our side.
Need help implementing?
Download our llms-full.txt and feed it into your AI coding tool (Claude Code, Cursor, Windsurf, etc.) for instant help with implementing these endpoints.