In today’s rapidly evolving blockchain ecosystem, developers and enterprises need reliable, scalable tools to access real-time on-chain data. One of the most essential functions in any Web3 infrastructure is the ability to query token balances across multiple chains for a given wallet address. This guide dives deep into a powerful API endpoint that enables exactly that—offering detailed insights into asset holdings across diverse blockchain networks.
Whether you're building a decentralized application (dApp), conducting blockchain analytics, or managing digital assets at scale, understanding how to retrieve comprehensive balance information is crucial.
What Is the Asset Balance API?
The Asset Balance API allows developers to fetch a complete list of token balances held by a specific blockchain address across multiple chains. It supports various asset types including:
- Native coins (e.g., ETH, BTC)
- ERC-20 tokens on EVM-compatible chains
- BRC-20, ARC-20, Runes, and SRC-20 tokens on Bitcoin
- Fractal Bitcoin (FBTC) BRC-20 tokens
This makes it an indispensable tool for multi-chain applications, portfolio trackers, and institutional-grade wallet services.
👉 Access real-time multi-chain balance data with powerful Web3 APIs
Supported Chains and Token Standards
The API is designed with cross-chain interoperability in mind. Here's a breakdown of supported ecosystems:
1. EVM-Compatible Chains
These include Ethereum, BNB Chain, Optimism, Arbitrum, Polygon, and more. All ERC-20 tokens issued on these networks are fully supported.
2. Bitcoin-Based Token Standards
Unlike traditional APIs that only support native BTC balances, this service extends support to emerging token standards on Bitcoin:
- BRC-20: Token standard leveraging ordinals and inscriptions
- ARC-20: Enhanced version of BRC-20 with improved functionality
- Runes: A lightweight fungible token protocol on Bitcoin
- SRC-20: Security-focused token standard on Bitcoin
3. Fractal Bitcoin Network
Supports FBRC-20 tokens, enabling developers to track assets on this high-throughput Bitcoin layer.
This broad compatibility ensures developers can build unified asset dashboards without needing separate integrations for each network.
Core Features
✅ Multi-Chain Balance Aggregation
Query up to 50 different chains in a single request using comma-separated chain identifiers. This reduces API call overhead and improves efficiency.
✅ Risk Token Filtering
Optionally filter out potentially risky or spammy airdrop tokens using the filter parameter:
filter=0: Exclude risk tokens (default)filter=1: Include all tokens, including those flagged as risky
This feature enhances security and user experience by preventing misleading balance displays from low-value or malicious airdrops.
✅ Detailed Balance Breakdown
Each response includes granular data points such as:
- Raw balance (in smallest unit, e.g., wei/satoshi)
- USD price per token
- Transferable vs. available amounts for inscription-based assets
- Token type classification (fungible token or inscription)
API Endpoint Overview
Request Path
GET https://web3.okx.com/api/v5/wallet/asset/all-token-balances-by-addressThis RESTful endpoint returns JSON-formatted responses containing full asset details.
Request Parameters
| 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) |
filter | String | No | Set to 0 to filter risk airdrop tokens; 1 to include them (default: 0) |
Example Request
GET https://web3.okx.com/api/v5/wallet/asset/all-token-balances-by-address?address=0x123...abc&chains=eth,bsc,btc&filter=0Response Structure
The API returns a JSON object with the following key fields:
Top-Level Field
tokenAssets: Array of token balance records
Each item in tokenAssets contains:
| Field | Type | Description |
|---|---|---|
chainIndex | String | Unique identifier for the chain |
tokenAddress | String | Contract address (or inscription ID for BRC-20) |
address | String | Wallet address queried |
symbol | String | Token symbol (e.g., USDT, ordi) |
balance | String | Formatted balance (e.g., "1.5") |
rawBalance | String | Raw amount in base units (e.g., "1500000") |
tokenPrice | String | Current USD price per token |
tokenType | String | 1: Fungible token; 2: Inscription (e.g., BRC-20) |
transferAmount | String | Amount immediately transferable (for inscription assets) |
availableAmount | String | Amount requiring minting/inscription before transfer |
isRiskToken | Boolean | Indicates if token is flagged as risky |
Example Response Snippet
{
"tokenAssets": [
{
"chainIndex": "eth",
"tokenAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"address": "0x123...abc",
"symbol": "USDT",
"balance": "1500.25",
"rawBalance": "1500250000",
"tokenPrice": "1.0",
"tokenType": "1",
"isRiskToken": false
}
]
}Practical Use Cases
📊 Portfolio Tracking Applications
Build real-time dashboards that aggregate holdings across Ethereum, BNB Chain, Bitcoin inscriptions, and Fractal Bitcoin—ideal for DeFi users managing diverse assets.
🔍 On-Chain Analytics Tools
Use the risk token filtering feature to clean datasets and avoid noise from spam airdrops when analyzing user behavior or market trends.
💼 Institutional Wallet Services
Integrate this API into custodial or non-custodial wallet platforms offering clients a unified view of their multi-chain portfolios.
👉 Unlock advanced blockchain data with scalable Web3 APIs
Frequently Asked Questions (FAQ)
Q: Which blockchains are supported by the Asset Balance API?
A: The API supports all major EVM chains (Ethereum, BSC, Polygon, etc.), Bitcoin with BRC-20/ARC-20/Runes/SRC-20 tokens, and Fractal Bitcoin with FBRC-20 support.
Q: Can I exclude suspicious or spammy airdrop tokens from results?
A: Yes. By setting the filter=0 parameter (default), the API automatically excludes known risk tokens. Set filter=1 to include all tokens.
Q: How does the API handle inscription-based assets like BRC-20?
A: For inscription tokens, the API distinguishes between transferAmount (immediately transferable) and availableAmount (requires inscription). This helps prevent user errors during transfers.
Q: Is there a limit to the number of chains I can query at once?
A: You can query up to 50 chains in a single request by providing a comma-separated list in the chains parameter.
Q: Does the API provide USD valuation for tokens?
A: Yes. The tokenPrice field returns the current market price in USD for each token, enabling instant portfolio valuation.
Q: Can I use this API for commercial applications?
A: Absolutely. This endpoint is part of a robust Web3 API suite designed for integration into dApps, analytics platforms, and enterprise solutions.
Best Practices for Integration
- Always validate the input
addressformat before making requests. - Cache responses where appropriate to reduce latency and API usage.
- Monitor
isRiskTokenflags to improve UI/UX by hiding low-value or potentially harmful tokens. - Use
rawBalancefor precise calculations (e.g., gas fees, transaction validation). - Combine with other Web3 APIs (e.g., transaction history, NFT holdings) for richer user experiences.
👉 Start building with secure, high-performance Web3 APIs today
Final Thoughts
The Asset Balance API represents a significant leap forward in multi-chain visibility and usability. By supporting both traditional fungible tokens and next-generation inscription standards like BRC-20 and Runes, it empowers developers to build truly unified Web3 experiences.
With features like risk filtering, USD pricing, and detailed balance breakdowns, this tool is not just functional—it’s future-ready.
Whether you're tracking DeFi positions, analyzing Bitcoin ordinals activity, or managing enterprise wallets, integrating this API streamlines access to critical on-chain financial data.
As blockchain adoption grows and asset fragmentation increases across layers and protocols, having a single source of truth for wallet balances becomes not just useful—but essential.