Tezos 链上的持仓账台：TzKT 开放接口查 NFT 的过滤与取数

以太坊生态的工具文章很少提 Tezos，但后者的 NFT 数据基础设施完成度很高：TzKT 是一条公开的 REST 接口层，把链上账户、合约、代币、余额、烘焙等对象全部做成可查询端点，浏览器 tzkt.io 和这套 API 读的是同一个索引器。想批量查一个钱包在 Tezos 上持有哪些 NFT、某个合约发过什么，不需要跑节点，一个 GET 请求就能起步。

先把 tokens 端点打开

接口根地址是 https://api.tzkt.io/v1/，根路径本身返回一份端点清单，tokens 一栏列出与代币相关的路由。Tezos 上的 NFT 绝大多数是 FA2 标准——对应社区提案 TZIP-12，相当于以太坊那边的 ERC-721 加 ERC-1155 合体，所以过滤 NFT 的钥匙是查询参数 standard=fa2：请求 GET /v1/tokens?standard=fa2，返回数组里每一项描述一个”合约加 token ID”的代币条目，字段包括合约地址、tokenId、standard 标识，以及 url 与 metadata 两个内容入口。元数据缺失的条目，这两个字段就是 null——这一点很重要，拿到 null 不代表资产不存在，只代表索引器没抓到或合约本身没挂元数据，需要转到合约存储或 URI 原文另行确认。

接口支持两个通用旋钮。limit 控制单次返回条数，翻页则靠 offset；select 决定每条记录留哪些字段，例如只要合约地址与 ID，可以写成 select=contract,tokenId——拉全量目录时裁剪字段能明显减负。

查持仓、查流转、回看历史

余额端点 GET /v1/tokens/balances 回答”谁持有多少”，可以按 account.address 过滤查一个地址的全部 FA2 持仓，也可以反向按 token.contract.address 查一件作品的持有人分布。想知道资产怎么流动起来，用 GET /v1/tokens/transfers，按合约与 tokenId 过滤就能拉出该件作品的完整转让史。更能体现索引器功力的是历史余额端点：GET /v1/tokens/historical_balances/{level} 允许按区块高度回看某一时点的持有权分布——空投快照、广播前对账、争议仲裁这类需求，靠它就不用自己重放交易。

把这些端点组合起来，一个典型的自查流程是：先用 balances 确认钱包持仓与链上一致；再对可疑条目用 tokens 端点核对元数据字段是否为空；最后用 transfers 看这件作品的来源是否干净。脚本化的场景同理：批量盯某个新合约的铸造进度，用 tokens 加 limit 轮询，比爬网页稳定得多。

索引器不是共识

用任何 API 都要记住同一句话：TzKT 读的是它自己的索引器，不是共识本身。端点的路径、参数与字段结构属于服务契约，会随版本演进——接口文档页给出的 OpenAPI 描述文件才是当前契约的正式文本，写生产脚本前先以它核对字段名。同理，API 与链上出现分歧时，以合约视图与节点数据为准。Tezos 上许多钱包界面背后就是这类公共索引器，把查询从”信平台”降格为”信可复算的索引”，是普通用户在这个生态里最容易建立的数据素养。

FA2 的两段式身份

写查询之前得先换掉以太坊的心智模型。FA2 里一件 NFT 的唯一身份是合约地址加 token ID 的二元组，链上不存在全局注册表把所有 ID 映射到作品；它的授权模型也不照搬以太坊的无限额度概念，转账语义依赖各合约自己的实现。因此任何查询都要两个字段一起给：只报 ID 没有意义，只报合约只能拿到整个合集。TzKT 的 tokens 端点返回的正是这个二元组的展开，账户加余额的组合回答持有关系，把两段式记熟，Tezos 上所有数据工具的用法就通了。

一次完整的铸造核对

把端点串起来演练一遍：项目公告给了合约地址与你的 ID；先请求 GET /v1/tokens?contract.address=KT地址&tokenId=编号，确认代币记录存在且元数据字段非空；再请求 GET /v1/tokens/balances?account.address=你的地址&token.contract.address=KT地址，确认余额指向你；最后翻 GET /v1/tokens/transfers?token.contract.address=KT地址，看第一手转移是否来自铸造。三步全绿才算真实落袋；哪一步红，问题就在那一步——元数据为空就去查合约自己的视图，查不到持仓多半是过滤条件写错。整套核对没有一环需要相信项目方的网页。 本文为机制说明，不构成任何投资建议。