Get Wallet Balance

POST

/wallets/balance

Retrieves the current balance of a specific wallet across all supported cryptocurrencies. This endpoint provides detailed information about available and pending balances for each cryptocurrency in the wallet.

Request Parameters

Parameter	Type	Description
wallet_id required	string	The unique identifier of the wallet
currency optional	string	Filter results to a specific cryptocurrency
include_zero_balances optional	boolean	Include cryptocurrencies with zero balance (default: false)

Example Request

POST /wallets/balance
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "wallet_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Parameters

Parameter	Type	Description
wallet_id	string	The unique identifier of the wallet
wallet_name	string	The name of the wallet
balances	object	Object containing balances for each cryptocurrency
total_usd_value	number	Total value of all balances in USD
last_updated	string	ISO 8601 timestamp of when the balances were last updated

Balance Object Structure

Each key in the balances object represents a cryptocurrency code. The value is an object with the following structure:

Parameter	Type	Description
available	number	The available balance amount
pending	number	The amount in pending transactions
total	number	The total balance (available + pending)
usd_value	number	The equivalent value in USD
address	string	The cryptocurrency address for deposits
blockchain	string	The blockchain network (e.g., ETH, BSC, TRX)
last_transaction_at	string	ISO 8601 timestamp of the last transaction

Example Response

{
  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
  "wallet_name": "Player Account",
  "balances": {
    "btc": {
      "available": 0.025,
      "pending": 0.01,
      "total": 0.035,
      "usd_value": 1421.75,
      "address": "3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5",
      "blockchain": "BTC",
      "last_transaction_at": "2025-04-28T09:12:33.456Z"
    },
    "eth": {
      "available": 0.5,
      "pending": 0,
      "total": 0.5,
      "usd_value": 1100.00,
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "blockchain": "ETH",
      "last_transaction_at": "2025-04-15T14:22:45.678Z"
    },
    "usdt": {
      "available": 500.00,
      "pending": 100.00,
      "total": 600.00,
      "usd_value": 600.00,
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "blockchain": "ETH",
      "last_transaction_at": "2025-04-29T16:30:12.345Z"
    }
  },
  "total_usd_value": 3121.75,
  "last_updated": "2025-04-30T16:45:22.123Z"
}

Error Codes

Status Code	Error Code	Description
400	invalid_request	The request was malformed or missing required parameters
401	authentication_failed	Authentication failed. Check your API key or OAuth 2.0 access token
403	insufficient_permissions	Your API key does not have permission to view wallet balances
404	wallet_not_found	Wallet with the specified ID was not found
404	currency_not_found	The specified currency is not supported
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint

Notes

This endpoint replaces the previous GET /wallets/:accountId/balances endpoint.
By default, only cryptocurrencies with non-zero balances are included in the response.
The pending amount represents funds that are in active transactions (e.g., deposits in processing status).
The available amount represents funds that can be used for withdrawals or transfers.
The total amount is the sum of available and pending amounts.
USD values are calculated based on current market rates and are for informational purposes only.
The address field provides the deposit address for each cryptocurrency.

iGaming Integration Note

Online casino operators should use this endpoint to retrieve player balances and display them in the casino interface. Implement a wallet dashboard that shows both available and pending balances for each cryptocurrency, along with USD equivalent values. Refresh balances periodically (every 1-2 minutes) during active sessions and always check before processing gameplay bets to ensure sufficient funds are available. For VIP players with high transaction volumes, consider more frequent balance checks.