Querying Specific Token Balances by Address

Overview

Learn how to query balances of specific tokens associated with a blockchain address using Web3 API. This guide provides detailed instructions on request parameters, response formats, and practical examples.

API Endpoint

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

Request Parameters

Parameter	Type	Required	Description
`address`	String	Yes	Blockchain address to query.
`tokenAddresses`	Array	Yes	List of token contract addresses (max 20). Includes:
> `chainIndex`	String	Yes	Unique chain identifier (e.g., `1` for mainnet).
> `tokenAddress`	String	Yes	Token contract address. Leave empty (`""`) for mainnet coins. For inscriptions (e.g., BRC-20), use formats like `btc-brc20-ordi`.
`filter`	String	No	`0`: Exclude risky airdrop tokens (default). `1`: Include all tokens.

Response Parameters

Parameter	Type	Description
`tokenAssets`	Array	List of token balances.
> `chainIndex`	String	Chain identifier.
> `tokenAddress`	String	Token contract address.
> `symbol`	String	Token symbol (e.g., ETH).
> `balance`	String	Token balance.
> `rawBalance`	String	Raw token balance (if supported).
> `tokenPrice`	String	USD price per token.
> `tokenType`	String	`1`: Standard token. `2`: Inscription.
> `transferAmount`	String	Transferable balance for inscriptions.
> `availableAmount`	String	Pending inscription balance.
> `isRiskToken`	Boolean	`true` if token is flagged as risky.

Example Request

{
  "address": "0x123...abc",
  "tokenAddresses": [
    {
      "chainIndex": "1",
      "tokenAddress": "0x456...def"
    }
  ],
  "filter": "0"
}

Example Response

{
  "tokenAssets": [
    {
      "chainIndex": "1",
      "tokenAddress": "0x456...def",
      "symbol": "OKT",
      "balance": "10.5",
      "tokenPrice": "25.30",
      "isRiskToken": false
    }
  ]
}

FAQs

1. How many token addresses can I query at once?

The API supports up to 20 token addresses per request.

2. What’s the difference between `balance` and `rawBalance`?

balance: Human-readable formatted balance.
rawBalance: Precise value in smallest unit (e.g., Wei for ETH). Supported only on specific chains.

3. How do I filter out risky tokens?

Set filter to "0" (default) to exclude tokens flagged as risky airdrops.

👉 Explore advanced Web3 API features

4. Can I query mainnet coin balances?

Yes. Pass an empty string ("") as tokenAddress for the chain’s native coin (e.g., ETH for Ethereum).

5. What formats are required for inscription tokens?

Use structured formats like btc-brc20-ordi for BRC-20 tokens or fbtc_fbrc20_babymusk for FBRC-20.

👉 Need help with token queries?

Key Takeaways

Use tokenAddresses to specify tokens and chains.