Querying Specific Tokens: A Comprehensive Guide to Wallet Asset Management

This guide explains how to query balances of specific tokens within a wallet account using Web3 API functionality.

Understanding Token Balance Queries

The token balance query feature allows users to retrieve balance information for designated tokens associated with their wallet. This functionality is essential for:

Portfolio tracking
Asset verification
Financial planning
Transaction preparation

👉 Explore advanced wallet management tools for comprehensive asset oversight.

API Request Structure

Endpoint

POST `https://web3.okx.com/api/v5/wallet/asset/token-balances`

Required Parameters

Parameter	Type	Required	Description
`accountId`	String	Yes	Unique account identifier
`tokenAddresses`	Array	Yes	List of tokens (maximum 20)
`chainIndex`	String	Yes	Blockchain network identifier
`tokenAddress`	String	Yes	Token contract address ("" for native currency)

Token Address Specifications

Native Currency: Use empty string "" to query the chain's base currency
Standard Tokens: Provide the contract address
Inscription Tokens:
- FBRC-20: Format as fbtc_fbrc20_name
- BRC-20: Format as btc-brc20-tick(name)
- Runes: Format as btc-runesMain-tickId
- SRC-20: Format as btc-src20-name

Response Structure

Parameter	Type	Description
`tokenAssets`	Array	List of token balances
`chainIndex`	String	Blockchain identifier
`tokenAddress`	String	Token contract address
`symbol`	String	Token ticker symbol
`balance`	String	Formatted token amount
`rawBalance`	String	Raw token amount (when available)
`tokenPrice`	String	USD valuation
`tokenType`	String	`1` for token, `2` for inscription
`isRiskToken`	Boolean	Risk token indicator

👉 Learn about token security best practices to protect your assets.

Implementation Examples

Sample Request

{
  "accountId": "wallet_12345",
  "tokenAddresses": [
    {
      "chainIndex": "1",
      "tokenAddress": "0x123...abc"
    },
    {
      "chainIndex": "2",
      "tokenAddress": ""
    }
  ]
}

Sample Response

{
  "tokenAssets": [
    {
      "chainIndex": "1",
      "tokenAddress": "0x123...abc",
      "symbol": "TOK",
      "balance": "100.50",
      "rawBalance": "100500000000000000000",
      "tokenPrice": "1.25",
      "tokenType": "1",
      "isRiskToken": false
    }
  ]
}

FAQ Section

Q: What's the maximum number of tokens I can query at once?

A: The API supports querying up to 20 tokens in a single request.

Q: How do I query native currency balances?

A: For native currency (like ETH on Ethereum), use an empty string "" as the tokenAddress parameter.

Q: What does isRiskToken indicate?

A: This flag identifies potentially risky airdropped tokens that may have security or regulatory concerns.

Q: Why might rawBalance be empty?

A: Raw balance isn't available for all blockchain networks. The field will be empty for unsupported chains.

Q: How frequently should I check token balances?

A: For active traders, we recommend checking balances at least daily. Casual users might check weekly.

Q: Can I query historical balance information?

A: This particular endpoint provides current balances only. Historical data requires different API endpoints.