POST /balance

Beexar → Operator

Beexar sends this request to fetch the current player balance. It is called when the game loads and may be called periodically during gameplay.

---

Request

POST {balance_url}

Headers

Header	Value
Content-Type	application/json
X-REQUEST-SIGN	HMAC-SHA256 signature of request body

Body

Field	Type	Required	Description
account_id	string	Yes	Player account identifier
currency	string	Yes	Currency code — standard ("USD", "EUR") or custom ("CUSTOM_GOLD")
game_id	string	Yes	Game identifier (slug)
session_id	string	No	Session identifier (UUID) of the game URL the balance is read for

Example

{
  "account_id": "player_123",
  "currency": "USD",
  "game_id": "dice",
  "session_id": "7b115688-3849-490a-95bd-7c281d81c64c"
}

---

Response

Success (200 OK)

Field	Type	Required	Description
balance	string	Yes	Current player balance as decimal string

{
  "balance": "500.00"
}

Error Responses

HTTP Status	Twirp Code	api_code	Description
400	invalid_argument	101	Player not found or disabled
400	invalid_argument	403	Invalid or missing signature
500	internal	500	Internal server error

{
  "code": "invalid_argument",
  "msg": "Player not found",
  "meta": {
    "api_code": "101",
    "api_message": "Player not found"
  }
}

---

curl Example

curl -X POST https://casino.example.com/wallet/balance \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: abc123def456..." \
  -d '{
    "account_id": "player_123",
    "currency": "USD",
    "game_id": "dice"
  }'

---

Behavioral Rules

• Return the real-time balance — do not cache
• The game_id field provides game context for operators who maintain per-game balances
• This request does not modify the player’s balance
• If the player does not exist, return api_code 101