查询地址 Runes 资产 API 使用指南

本文档详细介绍了如何通过 API 查询特定地址下持有的 Runes 资产。该接口适用于开发者快速获取和管理相关区块链资产数据。

接口基本信息

请求地址

使用 GET 方法访问以下端点：

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

请求参数

参数名	类型	是否必填	说明
runesId	String	是	唯一代币标识符
walletAddresses	String	是	钱包地址，多个地址用逗号分隔，最多支持 20 个
cursor	String	否	游标，指向要获取的排序序列（最多 1000 条）
limit	Integer	否	分页大小，默认值为 10，最大为 100，返回最大条目数

返回参数详解

返回数据包含以下字段：

参数名	类型	说明
assetId	String	资产 ID（数据库主键，无实际意义）
tickerType	Integer	代币类型（4 代表 Runes）
ticker	String	代币名称
tickerId	String	代币 ID
ownerAddress	String	钱包地址
amount	String	UTXO 中的 XRC20 数量
chain	Integer	链类型
inscriptionNum	String	铭文编号
utxoTxHash	String	交易哈希
utxoVout	Integer	UTXO 输出索引
utxoValue	String	UTXO 值
txHash	String	交易哈希
name	String	代币名称
tickerIcon	String	代币图标链接
status	Integer	挂单状态（0-未挂单，1-已挂单，2-挂单中）
listTime	Long	挂单时间
orderId	Long	订单 ID
confirmations	Long	区块高度信息
currency	String	总价格 - 货币单位
currencyUrl	String	总价格 - 货币单位链接
satPrice	BigDecimal	总价格，以 sat 为单位
price	BigDecimal	总价格，以 BTC 为单位
usdPrice	BigDecimal	总价格，以 USD 为单位
unitCurrency	String	单价 - 货币单位
unitCurrencyUrl	String	单价 - 货币单位链接
unitSatPrice	BigDecimal	单价，以 sat 为单位
unitPrice	BigDecimal	单价，以 BTC 为单位
unitUsdPrice	BigDecimal	单价，以 USD 为单位
unavailable	Integer	1-UTXO 包含多个 Atomicals 资产；2-UTXO 包含多个协议资产
symbol	String	代币符号

使用示例

以下为调用该接口的示例请求和响应内容：

请求示例

curl -X GET "https://web3.okx.com/api/v5/mktplace/nft/runes/get-owned-asserts?runesId=example_id&walletAddresses=addr1,addr2&limit=20"

响应示例

{
  "code": "0",
  "data": [
    {
      "assetId": "12345",
      "tickerType": 4,
      "ticker": "RUNESEXAMPLE",
      "tickerId": "id123",
      "ownerAddress": "addr1",
      "amount": "1000",
      "chain": 1,
      "inscriptionNum": "100256",
      "utxoTxHash": "a1b2c3d4e5...",
      "utxoVout": 0,
      "utxoValue": "5000",
      "txHash": "f6g7h8i9j0...",
      "name": "Example Rune",
      "tickerIcon": "https://example.com/icon.png",
      "status": 1,
      "listTime": 1640995200000,
      "orderId": 67890,
      "confirmations": 650000,
      "currency": "BTC",
      "currencyUrl": "https://example.com/btc.png",
      "satPrice": 55000,
      "price": 0.00055,
      "usdPrice": 25.50,
      "unitCurrency": "BTC",
      "unitCurrencyUrl": "https://example.com/btc.png",
      "unitSatPrice": 55,
      "unitPrice": 0.00000055,
      "unitUsdPrice": 0.0255,
      "unavailable": 0,
      "symbol": "EXR"
    }
  ],
  "msg": ""
}

应用场景

该接口适用于以下典型场景：

资产管理平台：为用户展示其持有的 Runes 资产清单
交易监控工具：实时追踪特定地址的代币变动情况
数据分析系统：统计和汇总链上资产分布与流动性

👉 查看实时资产查询工具

常见问题

什么是 Runes 代币？

Runes 是基于比特币网络的同质化代币协议，类似于 BRC-20 标准，但采用 UTXO 模型进行资产跟踪和转移，具备更高的效率和兼容性。

如何获取 runesId？

runesId 是代币的唯一标识符，通常可在代币发行信息、区块链浏览器或项目官方文档中查询得到。

支持批量查询多个地址吗？

支持。您可以在 walletAddresses 参数中传入多个钱包地址，以英文逗号分隔，最多支持 20 个地址同时查询。

返回数据中的 status 字段有哪些状态？

status 表示挂单状态：

0：未挂单
1：已挂单
2：挂单中

如何对返回结果进行分页？

使用 cursor 和 limit 参数可实现分页。cursor 用于记录上一次请求的末尾位置，limit 控制每页返回的数据条数。

出现 unavailable 为 1 或 2 时代表什么？

这表示当前 UTXO 中包含多种资产：

1：UTXO 包含多个 Atomicals 协议资产
2：UTXO 包含多个不同协议的资产

这种情况可能需要进一步解析 UTXO 内容才能获得准确的资产信息。