Balance

We call this endpoint to retrieve the player's current balance. We never store player balances in our system.

The balance response should 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

Success Response

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	Balance with 5-digit precision ($10.00 = 1000000)

Error Response

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

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

Error Statuses

Status	Description
`SESSION_EXPIRED_ERROR`	Player session has expired
`PLAYER_NOT_FOUND_ERROR`	Player does not exist
`SESSION_NOT_FOUND_ERROR`	Session does not exist
`UNKNOWN_ERROR`	Any other error