在区块链世界，无论是个人用户还是开发者，快速、准确地获取一个地址在各条链上的资产状况都是高频刚需。无论是追踪持仓、分析投资组合，还是开发钱包类应用，一个强大且易用的资产查询接口至关重要。本文介绍的接口，正是为解决这一问题而生。
该接口支持通过单一地址，一次性查询其在多条区块链上的完整资产明细。其设计目标是为开发者和高级用户提供高效、全面且安全可靠的链上资产数据查询服务。
核心功能特性
广泛的链与资产类型覆盖
此接口的突出优势在于其卓越的兼容性，能够同时查询主流公链及各类数字资产，具体包括：
- 原生代币：各条链的基础原生资产（如 ETH、BNB 等）。
- EVM 链代币：所有兼容以太坊虚拟机（EVM）的链上的 ERC-20 标准代币。
- 比特币生态资产：全面支持比特币生态的创新资产协议，包括 BRC-20、ARC-20、Runes 以及 SRC-20 等多种铭文代币。
- Fractal 比特币链资产：特别支持 Fractal 比特币链上的 BRC-20 代币。
智能风险控制
安全是资产管理的重中之重。该接口内置了风险空投代币过滤功能。用户可选择是否自动过滤掉被标记为潜在风险的虚假空投代币，有效保护自己免受诈骗和恶意代币的侵害，防止误操作导致的资产损失。
接口调用详解
请求方式与路径
接口采用标准的 GET 请求方法，调用路径固定为：https://web3.okx.com/api/v5/wallet/asset/all-token-balances-by-address
关键请求参数
调用时，您需要提供以下核心参数：
- address (字符串，必填)
要查询资产余额的区块链地址。 - chains (数组，必填)
指定要查询的具体链列表。支持同时查询最多 50 条链，多条链之间用英文逗号,分隔。 filter (字符串，选填)
风险代币过滤开关。可选值为：0: 过滤掉风险空投代币（此为默认值，推荐使用）。1: 不过滤，返回所有代币。
解读返回结果
接口返回的 tokenAssets 数组包含了详尽的资产列表，每个资产对象都提供以下信息：
- chainIndex: 该资产所在链的唯一标识符。
- tokenAddress: 代币的合约地址。对于原生代币，此字段通常为空。
- symbol: 代币的标准符号（如 BTC, ETH, USDT）。
- balance: 格式化后的代币余额，便于阅读。
- rawBalance: 代币的原始余额精度。对于尚未支持的链，此字段可能为空。
- tokenPrice: 该代币的实时美元计价单位价格。
- tokenType: 资产类型标识，
1代表普通代币，2代表铭文资产。 - transferAmount 与 availableAmount: 专门针对铭文资产（如 BRC-20）的字段，分别表示可直接转移的交易余额和仍需完成铭刻过程的待可用余额。
- isRiskToken: 布尔值，明确标识该代币是否被系统判定为风险空投代币。
应用场景与最佳实践
此接口的强大功能使其适用于多种场景：
- 钱包应用开发：为您的用户提供清晰、全面的多链资产总览界面。
- 投资组合跟踪器：自动聚合用户在不同链上的资产，计算总净值并进行盈亏分析。
- DeFi 策略监控：监控特定地址在各种 DeFi 协议中的质押和流动池资产。
- 链上研究与分析：分析大户地址（Whale）或特定项目的国库资产分布情况。
调用时，建议始终开启风险代币过滤 (filter=0) 以保障安全。同时，合理规划需要查询的链列表，避免一次性请求过多不必要的数据，以优化响应速度。
常见问题
Q1: 这个接口可以查询哪些区块链的资产？
A: 接口支持查询极其广泛的区块链网络，包括但不限于 Ethereum、BSC、Bitcoin 及其各类生态链（如 Arbitrum、Polygon、Avalanche 等），并持续增加支持范围。具体可通过 chains 参数指定。
Q2: 什么是风险空投代币？为什么要过滤它们？
A: 风险空投代币通常是指未经请求、突然出现在您地址中的代币，它们可能是诈骗项目用来诱导用户访问恶意网站或进行授权钓鱼的诱饵。过滤功能能有效帮助您识别并避免与这些潜在有害资产交互，提升资产安全性。
Q3: transferAmount 和 availableAmount 有什么区别？
A: 这是针对比特币等链上铭文资产的特殊字段。transferAmount 代表当前已铭刻完成、可以立即转移或交易的余额。availableAmount 则代表已部署但尚未完成最终铭刻过程的余额，这部分资产暂时无法移动。
Q4: 接口的请求频率是否有限制？
A: 是的，为保证服务稳定，所有 API 接口通常都会有速率限制。建议查阅相关文档了解具体的限流策略，并在您的应用中做好适当的请求缓存和错误重试机制。
Q5: 如果我想查询的某条链暂时不支持怎么办？
A: 接口支持的网络列表在不断扩展。如果遇到暂未支持的链，其 rawBalance 等字段可能返回为空。您可以关注官方更新日志，以获取最新的支持链信息。