Balance

155 calls your wallet (signed with X-Marbles-Signature) to read the player's current balance. /balance is a read — return the balance for the player's session and move no money. We never store player balances in our system.

The balance response must be in the correct currency for the player's session (identified by clientSessionId).

Endpoint

POST /balance

Request

POST /balance HTTP/1.1
Host: your.game.api
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "clientSessionId": "06mnrpyv2qd9jbwhoniyimxsy",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "requestId": "4ec4a295-cd84-46df-b225-4b72bd84892c",
  "timestamp": "2025-06-15T14:30:00.000Z"
}

Request Fields

Field	Type	Description
`clientSessionId`	string	The player's session identifier
`clientPlayerId`	string	The player's unique identifier
`requestId`	string	Unique request identifier (UUID)
`timestamp`	string	ISO 8601 UTC timestamp of when the request was created

Response Contract

Always respond HTTP 200; put the outcome in status. We read the status field, not the HTTP code, to decide how to handle the response.

The full status set lives in Error codes — that is the canonical home for the enum across all callbacks. For /balance the relevant outcomes are:

`status`	When you return it	What 155 does
`SUCCESS`	Balance read successfully	Returns the `balance` + `currency` to the session
`UNKNOWN_ERROR`	Unexpected operator-side failure	155 retries / surfaces the read failure

Never return a non-200 HTTP status or a bare error body — always respond 200 with one of the status values above. A non-200 is read as a transport failure.

/balance is a read and moves no money, so there is no idempotency rule — every call simply returns the player's current balance.

Amounts

balance is an integer in minor units with per-currency precision (5-digit precision for most currencies, so $10.00 = 1000000). Return the exact integer for the session currency; do not round to display units. See Currencies for the precision of each supported currency.

Worked Example

Success

The current balance is returned in the player's session currency.

HTTP/1.1 200 OK
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "status": "SUCCESS",
  "requestId": "4ec4a295-cd84-46df-b225-4b72bd84892c",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "currency": "USD",
  "balance": 1000000
}

Response Fields

Field	Type	Description
`status`	string	`"SUCCESS"`
`requestId`	string	Echo back the request ID
`clientPlayerId`	string	Echo back the player ID
`currency`	string	ISO 4217 currency code
`balance`	int64	Current balance in integer minor units (5-digit precision: `$10.00 = 1000000`)

Error Response

HTTP/1.1 200 OK
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "status": "UNKNOWN_ERROR",
  "requestId": "4ec4a295-cd84-46df-b225-4b72bd84892c",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy"
}

See the Response Contract above for what 155 does with each status, and Error codes for the canonical enum.

On this page