如果你想深入某个 Runes 项目的真实成交情况，而不是只看地板价曲线，那么“交易历史接口”是绕不开的利器。下文拆解完整调用链路、字段含义、分页技巧以及高频踩坑点，并用通俗场景帮你把抽象参数变为可落地的查询方案。
接口总览
作用
查询指定 Runes 名称或 ID 的最新真实成交记录，获取：成交总量、成交均价、买家 & 卖家钱包、平台来源等字段。
地址
GET https://web3.okx.com/api/v5/mktplace/nft/runes/trade-history核心关键词
- Runes 交易历史
- Runes API
- 成交数据
- 链上查询
- 分页游标
- 时间范围过滤
请求参数拆解
runesIds（可选）
以英文逗号分隔的代币标识，上限 20 个；留空即查询所有 Runes 的成交。cursor（可选）
想做自动翻页？把上一次返回结果中的cursor回传即可无缝衔接。limit（可选）
单页条数，默认 10，最大 100。抓取批量数据时可适当抬高。startTime/endTime（可选，Unix 秒）
只对某段行情（如某晚 8 点到 10 点）感兴趣？直接塞时间戳即可锁范围。
请求代码片段
curl -G \
'https://web3.okx.com/api/v5/mktplace/nft/runes/trade-history' \
--data-urlencode 'runesIds=runeA,runeB' \
--data-urlencode 'limit=50' \
--data-urlencode 'startTime=1717238400' \
--data-urlencode 'endTime=1717242000'返回字段全景图
| 关键字段 | 意义 & 使用场景 |
|---|---|
txHash | 区块浏览器的直接入口，点进去验证交易真伪。 |
from/to | 追踪巨鲸调仓或空投猎手。 |
typeName | SALE、TRANSFER、MINT，快速区分销售 & 转账。 |
usdPrice | 无须额外计价，即可换算成本位美元。 |
currency | Runes 交易的结算方式，常见有 BTC、SATS。 |
status | 只有 1（成功）才计入实际成交量，2（pending）可忽略。 |
场景示例
场景一：想监测“DOG•GO•TO•THE•MOON”在周六晚上的集中抛压，把 startTime/endTime 设置为当晚 21:00 到 24:00，即可实时爬取这一时段所有成交，用脚本算售出均价与总量，预警砸盘。
场景二：批量拆地板。有 100 个不同 Runes 需要动态采集最新成交，于是先以 limit=100 单次批量抓取，再通过 cursor 持续翻页，减少网络往返次数。
👉 一站式解析 Runes 背后的真实成交动能，立刻点击察看实战案例！
分页 & 性能调优 Tips
- 当数据量>1,000 条，建议 后端 流式处理：每次取 100 笔，秒级插表再遍历。
- 将
cursor存本地缓存（Redis），中断后秒级续爬，避免丢单。 - 时间范围与分页组合使用，可把单次响应时间稳定在 200 ms 内。
FAQ
Q1：是否支持一次查询超过 20 个 Runes ID？
A：目前官方限制 20 个，如更多请分批发起，然后本地聚合。
Q2：时间戳用毫秒还是秒？
A：必须是 Unix 秒级（10 位），若使用毫秒会得到空集。
Q3：usdPrice 是如何计算的？
A：后台以链上结算瞬间 BTC/USD 现货指数捕价，误差控制在 0.5% 以内。
Q4：cursor 会失效吗？
A：cursor 有效期 24 小时；过期后需要重新发起不带 cursor 的最早请求。
Q5：为什么出现 status=2 的 pending 记录？
A：链上确认未完毕，交易不满足查询共识深度，可直接跳过。
Q6：能否只筛选 MINT 事件？
A：在返回结果里二次判断 typeName == MINT，当前接口不支持请求级过滤。
结语 & 下一步行动
掌握以上 6 组参数与 3 种典型场景，你已经具备从“看行情”跃迁到“看链上成交”的能力。现在就把接口加入脚本，跑一段真实数据，观察巨鲸地板扫货节奏；或者把历史成交导进 Excel，做你自己的 Runes 价格模型。