balance — Balance Inquiry

Retrieves the player's current balance. This is the only callback that does not move money, and it is not retried on failure.

POST {wallet_base_url}/balance

When It Is Called

Moment	Description
Entering the game screen	When the player arrives via the launch URL and the lobby or game screen first loads. If a balance was received within the last 10 seconds, that value is used and no call is made
Balance refresh	When the player refreshes the balance on screen. At most once every 10 seconds per connection
Connection check	When the platform tests connectivity and signing after the integration application (Connection Check)

The platform also shows the balance from debit, credit, and rollback responses on the player's screen immediately, so it does not call balance separately for every bet or settlement. It is not called at game launch (POST /launch) either.

Request

Headers are the same as the common headers.

Field	Type	Required	Description
external_id	string	●	Operator-side player ID
player_id	string | null	●	Platform player ID (pl_…), for reference. null in connection check calls
currency	string	●	Player currency (e.g. PHP)
operator_session_id	string | null	●	The value sent at game launch. null if none was sent

POST /wallet/balance HTTP/1.1
Host: api.example-casino.com
Content-Type: application/json; charset=utf-8
X-Operator: acme
X-Timestamp: 1792547400123
X-Nonce: Q2x7mN0pR4sT8vW1yZ3bC5dE
X-Signature: 5f0c1e9a…(64 hex characters)

{"currency":"PHP","external_id":"u-102938","operator_session_id":"s-88af21","player_id":"pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b"}

Response

Field	Type	Required	Description
status	string	●	OK or an error status
balance	integer	● when OK	Current balance, integer in the minor unit

Success

{ "status": "OK", "balance": 1250000 }

Player not found

{ "status": "PLAYER_NOT_FOUND" }

Currency mismatch

{ "status": "CURRENCY_MISMATCH" }

Signature error

{ "status": "INVALID_SIGNATURE" }

status	When to use
OK	When returning the balance. Always include balance
PLAYER_NOT_FOUND	When no player matches the external_id
CURRENCY_MISMATCH	When the request currency differs from the player's currency
INVALID_SIGNATURE	When signature verification fails
INVALID_REQUEST	When external_id is empty or the body is malformed
UNKNOWN_ERROR	Any other internal error

You may return OK for a balance inquiry even if the player is blocked. Betting is blocked by PLAYER_BLOCKED on debit.

Platform Behavior

Result	Platform handling
OK + balance	Shows the balance on screen and caches it for 10 seconds
OK without balance	Treated as a failure
A status other than OK, 3-second timeout, non-HTTP-200, connection failure	If a balance known within the last 10 seconds exists, that value is shown; otherwise the balance is left blank (on screen entry) or a refresh failure (WALLET_UNAVAILABLE) is reported

• Not retried. A failed balance inquiry does not block betting — whether a bet is possible is determined solely by the debit result.
• balance must not change the balance. Implement it as read-only.