Get Wallet Balance

POST

/wallets/balances/

Retrieves the current balances of a specific wallet across all supported cryptocurrencies. You can look up a wallet by either its wallet_id or external_id.

Request Parameters

Parameter	Type	Required	Description
wallet_id	string	Yes*	The system-assigned wallet identifier
external_id	string	Yes*	Your unique identifier for the wallet

* One of wallet_id or external_id is required. If both are provided, wallet_id takes precedence.

Authentication

This endpoint requires authentication using one of the following methods:

Authentication Type	Header	Description
OAuth 2.0	Authorization	Bearer your_access_token
API Key	X-API-Key	your_api_key

Example Request

curl -X POST "{{BASE_URL}}/wallets/balances/" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "w_abc123def456"
  }'

Or using external_id:

curl -X POST "{{BASE_URL}}/wallets/balances/" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "player-12345"
  }'

Response

Field	Type	Description
account	object	Wallet account details
balances	array	Array of balance objects for the wallet

Balance Object

Field	Type	Description
currency	string	Currency code (e.g., "USDTTRC20", "BTC")
amount	number	Total balance amount
pending_amount	number	Amount in pending transactions
available_balance	number	Balance available for transfers

Example Response

{
  "account": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Player 12345",
    "external_id": "player-12345",
    "wallet_id": "w_abc123def456"
  },
  "balances": [
    {
      "currency": "USDTTRC20",
      "amount": "500.00",
      "pending_amount": "100.00",
      "available_balance": "400.00"
    },
    {
      "currency": "BTC",
      "amount": "0.025",
      "pending_amount": "0.00",
      "available_balance": "0.025"
    }
  ]
}

Error Codes

Status Code	Error Code	Description
400	invalid_request	Missing both wallet_id and external_id
401	unauthorized	Authentication failed
403	forbidden	User doesn't have required permissions
404	not_found	Wallet not found
500	server_error	Internal server error

Error Response Format

{
  "error": {
    "code": "not_found",
    "message": "Wallet not found",
    "details": {}
  }
}

Notes

• This endpoint accepts POST with a JSON body, not GET with a path parameter.
• The available_balance represents funds that can be used for transfers (total minus pending).
• The pending_amount represents funds in active transactions (e.g., deposits being confirmed).
• Required scopes: read, write.

iGaming Integration Note

Use this endpoint to retrieve player balances and display them in your casino interface. Implement a wallet dashboard that shows both available and pending balances for each cryptocurrency. Refresh balances periodically during active sessions and always check before processing gameplay bets to ensure sufficient funds are available.