Get Wallet Balance

This endpoint returns the balance information for a specific wallet.

Request

GET /wallets/balances

Query Parameters

Parameter	Type	Required	Description
wallet_id	string	Yes	The ID of the wallet to retrieve balances for

Authentication

This endpoint requires authentication using one of the following methods:

• API Key: X-API-Key header
• OAuth 2.0: Authorization: Bearer {access_token} header

Example Request

curl -X GET "{{BASE_URL}}/wallets/balances?wallet_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your_api_key"

Response

A successful response returns the balance information for the specified wallet, including all currencies and their amounts.

Example Response

{
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Trading Wallet",
    "balances": [
      {
        "currency": "usdttrc20",
        "amount": "1000.50",
        "pendingAmount": "0.00"
      },
      {
        "currency": "usdterc20",
        "amount": "500.75",
        "pendingAmount": "100.00"
      },
      {
        "currency": "btc",
        "amount": "0.05",
        "pendingAmount": "0.00"
      }
    ]
  }
}

Response Fields

Field	Type	Description
result.id	string	The ID of the wallet
result.name	string	The custom name of the wallet
result.balances	array	Array of balance objects

Each balance object contains:

Field	Type	Description
currency	string	Currency code in lowercase (e.g., "usdttrc20")
amount	string	Available balance amount (as string)
pendingAmount	string	Amount in pending transactions (as string)

Error Responses

Status Code	Error	Description
400	Bad Request	Missing or invalid wallet ID
401	Unauthorized	Authentication failed
403	Forbidden	User doesn't have required permissions
404	Not Found	Wallet ID not found
500	Internal Error	Server error while processing request

Notes

• The wallet ID must be valid and previously obtained from creating a wallet or listing wallets
• The balances are returned in the native currency units (e.g., USDT, BTC)
• The pendingAmount represents funds that are part of in-progress transactions and cannot be withdrawn
• The total available amount for a currency is amount - pendingAmount
• Balance information is automatically updated whenever transactions occur
• If no balances exist for the wallet, an empty balances array will be returned