Asset Details: Token Balance Inquiry by Address & Chain

Discover how to efficiently retrieve comprehensive token balance data across multiple blockchain networks using a powerful Web3 API. Whether you're tracking mainnet cryptocurrencies, ERC20 tokens on EVM-compatible chains, or emerging BRC-20 and Runes assets on Bitcoin-based networks, this guide breaks down the full functionality of the Asset Details API—a critical tool for developers, analysts, and blockchain applications.

Designed for seamless integration and real-time insights, this endpoint delivers accurate, structured balance information while supporting advanced filtering options such as risk-based airdrop detection.

What Is the Asset Details API?

The Asset Details API enables users to query token balances held by a specific wallet address across multiple blockchains. This includes both native coins and various token standards, making it ideal for multi-chain analytics, portfolio tracking, and security monitoring.

With support for EVM chains, Bitcoin-adjacent protocols like BRC-20 and Runes, and upcoming Fractal Bitcoin integrations, this API serves as a unified interface for cross-chain asset visibility.

👉 Access real-time blockchain balance data with powerful Web3 tools

Supported Asset Types

This API supports a wide range of digital assets across different blockchain ecosystems:

Mainnet Coins: Native cryptocurrencies like ETH, BTC, etc.
ERC20 Tokens: On any EVM-compatible chain (e.g., BSC, Polygon, Arbitrum).
Bitcoin-Based Tokens:
- BRC-20
- ARC-20
- Runes
- SRC-20
Fractal Bitcoin Tokens: FBRC-20 (Fractal Bitcoin’s version of BRC-20)

Additionally, the API includes an optional filter to exclude risk-flagged airdrop tokens, helping enhance data accuracy and reduce noise in portfolio analysis.

Request Endpoint

Use the following GET request to fetch asset details:

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

This RESTful endpoint returns structured JSON responses containing token balances, pricing, and metadata.

Request Parameters

To customize your query, pass the following parameters in the request URL:

Parameter	Type	Required	Description
`address`	String	Yes	The wallet address to query (e.g., `0x...` or Bitcoin address).
`chains`	String	Yes	Comma-separated list of chain identifiers (max 50). Example: `eth,bsc,btc`.
`filter`	String	No	Set to `0` to filter out risky airdrop tokens (default), or `1` to include all.

🔍 Pro Tip: Use precise chain codes to avoid response bloat and improve performance. For example, only request eth,polygon if you're analyzing Ethereum and Polygon assets.

Response Structure

The API returns a JSON object with a tokenAssets array containing detailed balance records. Each record includes the following fields:

Core Balance Information

chainIndex: Unique identifier for the blockchain (e.g., eth, btc).
tokenAddress: Smart contract address (for tokens); null for native coins.
address: Wallet address queried.
symbol: Token ticker symbol (e.g., USDT, BTC).
balance: Formatted token balance (human-readable).
rawBalance: Raw balance in base units (e.g., wei/satoshi). Note: May be empty for unsupported chains.
tokenPrice: Current market price in USD.
tokenType: Indicates whether the asset is a regular token (1) or an inscription-based asset (2, e.g., BRC-20).

Special Fields for Inscription Assets

For BRC-20, FBRC-20, and similar token types:

transferAmount: The amount that can be directly transferred or traded ("transferable balance").
availableAmount: The amount requiring inscription before it can be moved ("available" or "pending inscription" balance).

Risk Detection Flag

isRiskToken: Boolean value indicating if the token is flagged as a risky airdrop (true or false). Controlled by the filter parameter.

Use Cases & Applications

This API is highly versatile and applicable in numerous scenarios:

📊 Multi-Chain Portfolio Trackers

Build dashboards that aggregate holdings from Ethereum, Binance Smart Chain, Bitcoin layers, and more—ideal for DeFi platforms and investor tools.

🔐 Security & Fraud Monitoring

Identify suspicious airdrop tokens automatically using the isRiskToken flag to protect users from scams.

💬 Wallet Integrations

Enhance non-custodial wallets with real-time balance updates across EVM and non-EVM chains.

🧠 Blockchain Analytics Tools

Power research platforms with granular data on token distribution, user holdings, and market trends.

👉 Unlock advanced blockchain analytics with Web3-ready APIs

Frequently Asked Questions (FAQ)

Q: Can I query balances for both Ethereum and Bitcoin addresses in one call?
A: Yes! Just include both chain identifiers in the chains parameter (e.g., eth,btc). The API will return all supported tokens from each specified network.

Q: What does “rawBalance” mean?
A: It refers to the unformatted balance in the smallest unit of the token (e.g., wei for ETH, satoshis for BTC). This is useful for precise calculations in smart contracts or backend systems.

Q: How does the risk airdrop filter work?
A: The system flags tokens commonly associated with spam or malicious campaigns. Setting filter=0 excludes them; setting filter=1 shows all tokens regardless of risk status.

Q: Are BRC-20 balances fully transferable?
A: Not always. The transferAmount field shows how much can be moved immediately, while availableAmount reflects funds needing inscription first.

Q: Is there rate limiting on this API?
A: While not detailed here, most production-grade APIs enforce usage limits. Always check official documentation or contact support for quota details.

Q: Does this support testnet chains?
A: Currently focused on mainnet chains. Check the latest Web3 API docs for future testnet expansions.

Example Usage

Sample Request

GET https://web3.okx.com/api/v5/wallet/asset/all-token-balances-by-address?address=0x123...abc&chains=eth,polygon&filter=0

Sample Response

{
  "tokenAssets": [
    {
      "chainIndex": "eth",
      "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "address": "0x123...abc",
      "symbol": "USDT",
      "balance": "1500.25",
      "rawBalance": "1500250000",
      "tokenPrice": "1.00",
      "tokenType": "1",
      "isRiskToken": false
    },
    {
      "chainIndex": "btc",
      "tokenAddress": "",
      "address": "bc1qxyz...",
      "symbol": "BRC-20",
      "balance": "100.0",
      "rawBalance": "",
      "tokenPrice": "50.00",
      "tokenType": "2",
      "transferAmount": "80.0",
      "availableAmount": "20.0",
      "isRiskToken": true
    }
  ]
}

Key SEO Keywords

Asset details API
Token balance by address
Multi-chain wallet balance
BRC-20 balance check
Web3 balance inquiry
Blockchain asset lookup
EVM token query
Runes token support

These keywords are naturally integrated throughout the content to align with common search queries related to blockchain asset tracking and Web3 development.

Final Thoughts

The Asset Details API stands out as a robust solution for developers and businesses needing accurate, real-time insight into multi-chain wallet holdings. With native support for cutting-edge token standards like BRC-20 and Runes—and intelligent filtering for risky assets—it empowers applications to deliver cleaner, safer user experiences.

Whether you're building a next-gen wallet, analytics engine, or DeFi dashboard, leveraging this API ensures comprehensive coverage across both EVM and non-EVM ecosystems.

👉 Start integrating powerful Web3 APIs today – no signup required