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"
}

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)

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

Error Response

HTTP/1.1 401 Unauthorized
X-Marbles-Signature: <signature>
Content-Type: application/json

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

Error Statuses

Status	HTTP Code	Description
`SESSION_EXPIRED_ERROR`	400	Player session has expired
`PLAYER_NOT_FOUND_ERROR`	404	Player does not exist
`SESSION_NOT_FOUND_ERROR`	404	Session does not exist