深入解析 Ordinals 交易历史接口：快速检索 BTC NFT 与 Brc20 记录

借助专业的 Web3 开发工具与NFT 交易市场接口，你无需翻阅区块浏览器，也能在毫秒之间拉取任意 BTC NFT 集合或 Brc20 TOKEN 的最新深度成交数据。本文将带你完整拆解 Ordinals API 的 trade-history 请求与返回细节，并给出现成案例与常见问题，让部署到任何 Web3 应用都变得简单高效。

接口总览：一句话搞懂「交易历史」在做什么

通过一个 POST 请求即可向节点索要历史挂单或成交记录，支持同时 区分 BTC NFT 与 Brc20、自定义平台来源及 单一口袋地址过滤，并自带分页与排序能力，核心 关键词：BTC NFT、Brc20 记录、offset 分页、链上数据、交易市场、inscriptions、price 记录。

请求地址及调用方式

POST https://web3.okx.com/api/v5/mktplace/nft/ordinals/trade-history

请求头：Content-Type: application/json
接口限频：单次最大返回 100 条记录，默认 10 条
统一认证：标准签名 & API-KEY 方式，可在创建时申请

关键入参拆解

入参	必填	示例值	作用解读
slug	✅	`"btc-punks"`	集合唯一标识符，大小写敏感
cursor		`"eyJpZCI6MTAwfQ==";`	分页游标，上一页最后一项的 cursor 回传即可
limit		`20`	每页条数，最大 100
sort		`desc` / `asc`	默认 `desc`，按时间倒序最快拿到最新事件
isBrc20		`false`	`true` 仅取 Brc20 记录，`false` 仅取 BTC NFT，默认 `true`
orderSourceList		`[34,54]`	只有来自 OKX(34) 与 Magic Eden(54) 的订单
tradeWalletAddress		`"bc1p..."`	只看该地址发起 / 接受的交易
type		`"SALE,UPDATE_PRICE"`	支持多类型并用 `,` 拼接，如 `SALE、LIST、TRANSFER、CANCEL_LIST`

实战小提示

精准过滤场景：如果只想拉大额卖单，可组合 type=SALE + limit=50 + sort=desc 直接抓最新高价成交。
👉 查看 3 个真实示例代码，直接复制即可跑通

响应结构一览

返回为一个数组（Array<OrdinalsActivity>），单个对象字段如下：

字段	类型	业务含义
fromAddress	string	转出地址
toAddress	string	接收地址
inscriptionId	string	铭文 ID，可用来二次调用铭文详情
price	string	单笔交易总价（BTC），数值化为后可与 unitPrice 乘积校验
unitPrice	string	单价（BTC / 个），便于测算顶部价格区间
amount	string	该笔订单包含的铭文数量
timestamp	long	时间戳，毫秒级可直接转日期
isBrc20	bool	`true` = Brc20；`false` = BTC NFT
orderSourceName	string	交易所来源，如 OKX、Magic Eden、Ordinals Wallet
type	string	SALE、LIST、TRANSFER、CANCEL_LIST、UPDATE_PRICE 五选一

完整请求 & 响应示例

1. 请求体

{
  "slug": "btc-punks",
  "limit": 5,
  "sort": "desc",
  "isBrc20": false,
  "type": "SALE"
}

2. 响应片段

[
  {
    "fromAddress": "bc1pabc123...",
    "toAddress": "bc1pdef456...",
    "inscriptionId": "238742",
    "price": "0.125",
    "unitPrice": "0.125",
    "amount": "1",
    "timestamp": 1717729800000,
    "isBrc20": false,
    "orderSource": 34,
    "orderSourceName": "OKX",
    "type": "SALE"
  },
  {...}
]

常见疑问 FAQ

**Q1.
slug 是什么，在哪找？**
A：slug 等于集合的 英文网址片段，判断方法——将你的 BTC NFT 页面 URL 中最后一级的 https://xxx.com/collection/ 之后部分即为 slug，例如 "btc-punks"，"ordinal-loops"。

**Q2.
如何抓取两个以上平台的数据却又不想丢记录？**
A：

先设置 orderSourceList=[34,54,55]；
每次 100 条 limit=100，分区存储；
使用 cursor 逐页循环，直到返回空数组为止。

**Q3.
timestamp 只到毫秒，怎么直接转成人类时间？**
A：Unix 毫秒除以 1000 → 秒，用 new Date(timestamp/1000) 可拿到 UTC+0；再根据自己服务器时区加偏移即可。

**Q4.
项目首页想只展示“历史最低价”，需要额外调用接口吗？**
A：不需要。你把全部 SALE 记录拉取，客户端做一次 price 最小值排序即可；若数据集较大，可考虑本地缓存 24h 历史快照。

**Q5.
调用频率有上限吗？**
A：当前策略是 每分钟 120 次，超出会返回 HTTP 429，请自行实现指数退避或本地缓存。

场景扩展：打造实时排行榜

鲸鱼追踪：把 tradeWalletAddress 换成已知“巨鲸”地址，每分钟轮询，对比上一条记录找出新成交。
地板价监控：仅抓 type=LIST，用 unitPrice 升序排序，第 1 条即为地板价。
批量舆情：配合推文关键词 Brc20 record，把 API 拿到的热点铭文 ID 嵌进内容，完成自动化播报。

进阶技巧：如何优雅分页「避免重复」

首次查询：不附带 cursor，拿到第 1 页。
缓存 cursor：把返回最后一项的 cursor 存入 Redis 或数据库，下一请求带上。
时钟漂移保护：在执行前用 now-60s 的时间戳记录上一次拉取终点，保证不漏单并有重叠冗余校验。

👉 点击下载可直接集成到你的 React/Next.js 项目的完整代码片段与错误处理模板

总结

无论你是 构建 NFT 实时监控工具、强化 Web3 交易情报站、抑或开发 链上数据分析 SaaS，这个 Ordinals API 的 交易历史端口都堪称“瑞士军刀”。掌握 slug 查找、参数组合与分页机制之后，仅需 20 行代码，就能把任意 BTC NFT / Brc20 集合的实时成交 feed 纳入你的系统核心面板。祝你早日冲上 Web3 MVP！