按元数据出价的两种写法：metadataId 与筛选条件，以及索引器滞后的代价

普通出价指定具体某一件 NFT，集合出价接受合集里任意一件，属性出价按稀有度属性筛选。Immutable 订单簿文档里还有一层更宽的类型：元数据出价（metadata bid），用代币的元数据本身当匹配条件。它提供两种互斥的写法，同时附带一个容易被忽略的前置依赖——订单簿的匹配不看链上现场，而是看索引器里的数据。

两种写法各有分工。第一种填一个 metadataId：这是 Immutable 索引器给一份元数据定义分配的 UUID，同一模板铸造出来的一批代币共享同一个 ID。市场若已经知道某个模板的 UUID，出价填它即可，成交时校验代币被索引到的元数据 ID 是否等于该 UUID，逻辑上是一比一的精确匹配。第二种填 metadataCriteria：一组字段级筛选器，每个筛选器指定字段名与允许值列表。字段名可以是顶层元数据字段（名称、图片、描述、动画链接、外链、视频链接六类），也可以是以 attribute: 前缀标记的单个属性。匹配语义是筛选器之间全满足、同一筛选器内的值满足其一，且不区分大小写。

两种写法只能选其一。文档明确：同时提供两者，或者两者都不给，都会被 SDK 与 API 层直接拒绝。这个约束的工程含义是防止歧义——当 UUID 与字段条件指向不同代币集合时，连撮合系统都无法回答“卖家交哪件算成交”。对使用者，先想清楚自己按“同源模板”还是按“字段长相”圈定目标，再动笔填表。

真正的隐性依赖在成交环节。文档提示：卖家吃你这口出价时，Immutable 要拿你指定的匹配条件校验他提交的 tokenId，而校验用的是索引器里的元数据。如果这件 NFT 的元数据缺失或过期——比如项目刚更新了属性、索引尚未追上——那么即便 NFT 在链上真实存在，成交也可能失败。换言之，元数据出价的对手方不是合约而是索引库，链上世界与撮合世界之间存在一段同步窗口，出价能否被吃，部分取决于这段窗口里索引的状态。

由此可以推出两条实操纪律。出价方：圈定条件前先在市场页面确认目标代币的属性已正确显示——显示本身就是索引器已收录的证据；用 metadataId 时优先选平台展示的稳定标识而不是自己拼字段。卖方：想接住某口条件出价时，先核对自己 NFT 的字段值与大小写、属性前缀写法是否落在允许值列表内；条件不区分大小写降低了错配概率，但属性名拼写差异（如尾空格、变体词）仍然致命。索引依赖还带来一个时间维度：刚铸造的 NFT 需要等索引追上才可能被条件出价匹配到，指望“铸完立刻被收单”的场景，失败原因常常不是没人出价，而是撮合系统还不认识这件 NFT。

这类订单在 API 里的类型字段是 METADATA_BID，与挂单、普通出价、集合出价、属性出价并列；文档也给了与属性出价的取舍建议：只按单个属性筛选时，属性出价更简单；需要把顶层字段（比如名称恰好等于某个字符串）一起纳入条件时，才动用元数据出价的 criteria 模式。把订单类型当菜单读，能更快定位自己需要的匹配语义；反过来，任何一类条件出价失效时，先用同一套排查顺序走一遍：订单类型是否用对、条件组合是否合法、索引是否收录、字段值是否精确命中，四层各查一次，多数“出价没人吃”的原因会在前两层现形。

最后是通用边界：条件式出价的匹配发生在撮合层，成交落链后仍走订单簿的标准流程，签名、授权、费率的规则与其他订单一致。索引依赖则是这类产品共有的软肋——不是 Immutable 独有，任何“按属性收单”的功能都必须先把数据搬进可查询的库里再谈匹配。理解这一点，看到出价迟迟没被吃时，你的排查清单里就会多一项：先查索引，再怀疑价格。

本文为机制说明，不构成任何投资建议。