Web3 钱包即服务：如何用 API 一键查询地址维度资产与特定代币余额

关键词：钱包 API、链上信息查询、地址维度资产、特定代币检索、Web3 开发、区块链数据、代币余额、铭文资产

想让你的 DApp 实时显示用户持有的 任意代币或铭文余额？只需要一条 POST 请求，就能把地址维度资产全部打捞上来，并自动过滤可疑空投。下文将手把手拆解调用流程，补充常见场景与 QA，让你在 10 分钟内跑通。

01 能力总览：为什么选用钱包即服务 API

钱包即服务提供了传统自建节点无法比拟的三大亮点：

低延迟——官方节点缓存 + CDN 全球加速，查询 200ms 内响应。
精准过滤——默认屏蔽风险空投币，减少后台二次清洗。
兼容多链主网、铭刻资产——ERC-20、BRC-20、FBRC-20、Runes、SRC-20 均可一站式读取。

02 接口概览

维度	内容
请求地址	`POST` https://web3.okx.com/api/v5/wallet/asset/token-balances-by-address
核心功能	查指定地址下，1-20 合约地址的余额与价值
额外特性	可选过滤风险空投币；返回可转/待铭刻铭文两类余额

03 请求报文深度拆解

3.1 必选字段

{
  "address": "0x2e0…AbC",               // 查询目标地址
  "tokenAddresses": [
    {
      "chainIndex": "1",               // 链唯一标识：以太坊主网
      "tokenAddress": ""               // 空字符串=查询 ETH 本身
    },
    {
      "chainIndex": "1",
      "tokenAddress": "0xA0b..."      // USDT 合约地址
    },
    {
      "chainIndex": "0",               // BTC 主网
      "tokenAddress": "btc-brc20-ordi" // BRC-20 铭刻代币 ordi
    },
    {
      "chainIndex": "0",
      "tokenAddress": "btc-runesMain-840000:2" // Runes 资产
    }
  ]
}

3.2 可选字段

参数	默认值	说明
filter	0	`0` 过滤风险空投，`1` 保留全部

04 返回示例解析

{
  "code":0,
  "msg":"",
  "data":[
    {
      "chainIndex":"1",
      "tokenAddress":"",
      "address":"0x2e0…AbC",
      "symbol":"ETH",
      "balance":"4.2287",
      "rawBalance":"4228700000000000000",
      "tokenPrice":"3205.31",
      "tokenType":"1",
      "isRiskToken":false
    },
    {
      "chainIndex":"0",
      "tokenAddress":"btc-brc20-ordi",
      "symbol":"ordi",
      "balance":"1500",
      "transferAmount":"1200",
      "availableAmount":"300",
      "tokenType":"2",
      "isRiskToken":false
    }
  ]
}

字段速记：

rawBalance：链上原生数值，用于链上写入。
transferAmount / availableAmount：BRC-20 特有，区分可转出与待铭刻余额。
tokenPrice：美元报价，可直接渲染前端资产总额。

👉 需要更细链名称对照表？一文精通所有 chainIndex 编码规则

05 场景实战：三种常见调用姿势

5.1 DApp 资产仪表盘

用户登录后，自动获取地址维度资产，并分组展示

ETH & 15 个主流 ERC-20
BTC 主网 + 最新 Runes 项目余额

实现要点：一次请求 tokenAddresses 上限 20，可把主链币填 ""，再追加 19 个合约即可。

5.2 NFT 市场空投排查

想避免用户挂单收到垃圾代币，对接时把 filter 固定置 0；黑名单实时更新无需自建脚本。

5.3 多钱包批量风控审计

交易所场景，后台轮询批量地址风险 isRiskToken，标记出可疑空投，随后触发告警。

06 带你写一段 Python 调用

import requests, json

url = "https://web3.okx.com/api/v5/wallet/asset/token-balances-by-address"
payload = {
    "address": "0x2e0…AbC",
    "tokenAddresses": [
        {"chainIndex":"1","tokenAddress":""},         # ETH
        {"chainIndex":"1","tokenAddress":"0xdAC..."}  # USDT
    ],
    "filter":0
}
res = requests.post(url, json=payload).json()
for item in res["data"]:
    print(f"{item['symbol']}：{item['balance']} (${item['tokenPrice']})")

FAQ | 常见问题

Q1：一次最多能查多少个地址？
——接口限制查询单个地址，但 tokenAddresses 列表最大 20 条。如需批量，“多线程 + 分片”仍是首选。

Q2：运行后提示 “tokenAddress 不合法”？
——请确认链标识与协议类型匹配：

ERC-20 用=1;
Runes 则用 0 且格式需满足 btc-runesMain-id:value，大小写敏感。

Q3：为何我查不到铭文余额？
——BRC-20 / Runes / SRC-20 的 address 必须是 Taproot (bc1p) 格式 或 Legacy (1/3 开头)，脚本地址需自行转换。

Q4：返回的 "tokenPrice" 多久更新一次？
——价格来自链下报价源，主流资产每 5 秒刷新；冷门铭文可能延迟到 1–2 分钟。

Q5：如何区分可转余额与待铭刻余额？
——看 tokenType=2 且 transferAmount != availableAmount，即有部分资产尚未铭刻，钱包无法直接转账。

Q6：会收取调用费用吗？
——目前处于公测阶段，免费调用但有 QPS 限制；未来速率提升版本会另行公告。

07 结语

通过 地址维度资产 查询接口，一条 POST 即可精确锁定用户持有的 特定代币及铭文余额，并自动兼顾安全过滤。不论是 DApp、钱包、还是去中心化交易所，都能把这一能力嵌入到资产首页、充值检测、风控大厅等模块。现在就动手实践，体验真正的 “钱包即服务” 便捷之处。