钱包 Runes 资产一键查看：完整调用指南与实战示例

借助 Runes API 的 get-owned-asserts 接口，开发者、交易者和研究者都能在几秒钟内精准获取任意比特币地址的 Runes（符文）持仓与挂单详情。本文将围绕 钱包资产查询、Runes API 和 市场 API 这三个核心关键词，深度拆解参数、场景、FAQ 及代码级用例，帮助你从一页文档新手进阶可落地上线的资深用户。

接口速览

作用

精准映射：返回指定地址对应 Runes 代币 的余额、挂单状态及价格。
批量查询：一次最多支持 20 个钱包地址的聚合返回，降低链上请求次数。
实时同步：监听 UTXO 状态与挂单动态，confirmations 字段确保区块高度信息最新。

端点

GET https://web3.okx.com/api/v5/mktplace/nft/runes/get-owned-asserts

3 组核心关键词速记

Runes API：Runes 资产查询、挂单、实时价格接口统称
钱包资产查询：获取某个 / 多个地址的 符文余额 与 交易细节
市场 API：延伸至挂单状态、价格、币种包括 BTC、USD、SAT 的实时计价

请求参数拆解

runesId（必填）
- 代币在 Runes 生态中的唯一 ID，区分大小写。
- 若需批量查多个代币，可重复发请求或分页。
walletAddresses（必填）
- 英文逗号分隔，最多 20 个字符型地址；示例
```
bc1pabcdef...,bc1pghijkl...
```
limit（分页，选填）
- 默认 10，最大 100。在高频数据场景下调整 range 可显著降低延迟。
cursor（游标，选填）
- 需要翻页时传入上一次返回的 cursor 字串，实现无断点遍历。

👉 一键查看参数模板与免费沙盒测试，立即跑通你的第一次 Runes API 调用！

返回字段导航

资产维度
- ticker：代币符号
- amount：该 UTXO 上 Runes 余额，字符串类型防精度丢失
- tickerIcon：图标 SVG/PNG 链接，可直接渲染到前端列表
链上状态
- utxoTxHash & utxoVout：精准定位钱包中的最小锁定单元
- confirmations：区块确认数，稳定应用在风控系统
市场状态
- status：挂单中 / 未挂单 / pending
- satPrice、price、usdPrice：多层计价，支持 Bots 做套利指标
- orderId：若资产处于挂单，可直接调用「取消订单」或「修改价格」接口
不可交易标识
- unavailable：1 表示同一 UTXO 同时存在符文 + 其他资产，交易时需分拆
- symbol：可与前端交易对匹配，防止误挂单

实战范例

Request（curl）

curl -G 'https://web3.okx.com/api/v5/mktplace/nft/runes/get-owned-asserts' \
  -H 'Accept: application/json' \
  -d 'runesId=RUNE_TEST_12345' \
  -d 'walletAddresses=bc1p0xyz...,bc1p1abc...' \
  -d 'limit=50'

Response 精简片段

{
  "code": 0,
  "msg": "",
  "data": [{
    "assetId": "124329",
    "ticker": "MAGIC",
    "amount": "1000000",
    "ownerAddress": "bc1p0xyz...",
    "price": "0.000005",
    "usdPrice": "0.26",
    "status": 1,
    "orderId": 887654321,
    "confirmations": 6,
    "unavailable": 0
  }, ...],
  "cursor": "eyJzZXEiOjk5fQ=="
}

场景示意：钱包持有 100 万枚 MAGIC，正在挂单中，对应 USD 计价约 0.26 美元。确认数 6 保障其可即时交易。

👉 走进演示项目源码，查看如何用 Node.js 批量拉取并解析 Runes 钱包资产

常见问题 FAQ

Q：「runesId」从哪里获取？
A：通过 Runes mint 交易回执、官方索引器或链上浏览器查询，格式通常为 ticker_decimals 组合。
Q：为什么返回空列表但链上确实有余额？
A：大概率是确认数不足 <6，或同一 UTXO 被标记为 unavailable = 2，需要拆分到独立 UTXO 后再查。
Q：能否直接按金额排序输出？
A：暂不支持服务端排序，可在前端拿到全部数据后，以 amount*usdPrice 本地排序。
Q：返回的图标地址跨域失败怎么办？
A：将 tickerIcon 作为镜像地址添加到后端代理或 CDN，统一设置 Access-Control-Allow-Origin: *。
Q：一次超过 20 个地址会被拒绝吗？
A：系统直接返回 400，建议分批请求并在前端做并发控制，节省 Rate Limit。
Q：挂单状态下还能继续转账该 UTXO 吗？
A：不能。挂单后该 UTXO 被锁定；如需转账，先调用「取消订单」接口，等待 status=0 后方可发起链上转移。

最佳实践小结

批量管理：结合 cursor 与 limit 做额度池快照，复用缓存数据减少重复请求。
风控校验：对比 confirmations 差值，防止双花攻击；对大于 100 万美元的挂单可二次签名确认。
价格聚合：将 satPrice、price、usdPrice 做标准化展示，避免用户理解的币种混乱。
低延迟策略：在前端轮询间隙写入 Redis，端上请求先到缓存再到链上，整体响应压到 50 ms 以内。

通过以上拆解，无论你是要打造新一代 Runes 生态钱包，还是在现有产品中嵌入 钱包资产查询 工具栏，都可基于本文一步到位的示例启程。祝你早日上线功能完备的 市场 API 应用！