Place bids on NFTs in a collection whose indexed metadata matches what you specify. A metadata bid can either target a group of tokens that share the same metadata ID (e.g. tokens minted from the same template), or it can match tokens by field-level criteria on the top-level metadata fields (Documentation Index
Fetch the complete documentation index at: https://docs.immutable.com/llms.txt
Use this file to discover all available pages before exploring further.
name, image, description, animation_url, external_url, youtube_url) and individual attributes.
See Getting Started for prerequisites and installation.
What is a metadata bid?
- You offer ERC-20 tokens to buy one or more NFTs from a collection, identified by an ERC-721 collection or ERC-1155 collection buy item.
- You attach exactly one matching spec:
metadataId— a UUID that identifies a group of tokens sharing the same metadata definition in Immutable’s indexer. The bid fills only on tokens whose indexedmetadata_idequals this UUID.metadataCriteria— an array of field-level filters. Each filter has afieldName(a top-level metadata field, or an attribute prefixed withattribute:) and a list of allowed values.
- Matching semantics for
metadataCriteria: every filter you specify must be matched (filters AND). For a given filter, the token matches if its value is one of the allowed values (values OR). Matching is case-insensitive. - Matching semantics for
metadataId: the token’s indexedmetadata_idmust equal the supplied UUID exactly. - Orders appear as
METADATA_BIDin API responses alongside listings, bids, collection bids, and trait bids. Use the ordertypefield when branching in your app or webhooks.
Prerequisites
- Same setup as other orderbook flows (Passport or wallet, fees, etc.).
- Metadata for fulfillment: when a seller fills your bid with a specific
tokenId, Immutable validates that token against your matching spec. That requires the NFT’s metadata to be available through Immutable’s indexer. If metadata is missing or out of date, fulfillment can fail even if the token exists on-chain.
Choosing between metadataId and metadataCriteria
| Mode | Use it when |
|---|---|
metadataId | The marketplace already knows the metadata stack UUID, e.g. “all tokens minted from template a1b2c3...”. One stable identifier, no field-level reasoning. |
metadataCriteria | You want to bid on tokens whose metadata satisfies a logical AND of human-readable conditions, e.g. “name is Cool Dragon AND background is Blue or Red”. |
Creating a metadata bid
The flow mirrors collection bids: prepare (buildsorderComponents, orderHash, and actions) → run any approval transactions → sign the EIP-712 order from the SIGNABLE action → create.
prepare, approval, and signing steps are identical for both modes. The third step — calling createMetadataBid — is where you pick the matching spec.
- By metadata ID
- By criteria
Supported fieldName values
In metadataCriteria mode, fieldName must be one of:
| Pattern | Meaning |
|---|---|
name | Matches the NFT’s top-level name field |
image | Matches the NFT’s top-level image field |
description | Matches the NFT’s top-level description field |
animation_url | Matches the NFT’s top-level animation_url field |
external_url | Matches the NFT’s top-level external_url field |
youtube_url | Matches the NFT’s top-level youtube_url field |
attribute:<trait_type> | Matches the value of the attribute whose trait_type equals <trait_type> (e.g. attribute:Background) |
fieldName may appear at most once per bid. The SDK rejects duplicates client-side — combine multiple acceptable values into a single filter’s values array (OR) instead.
Filling a metadata bid (seller)
Sellers callfulfillOrder with the metadata bid order id and the token ID they are selling into the bid. Pass undefined for amountToFill (standard ERC-721 fill) and supply tokenId as a string.
Querying metadata bids
List metadata bids
Filter by collection contract, status, maker, and pagination.Get one metadata bid
metadataId is undefined for criteria-mode bids, and metadataCriteria is an empty array for id-mode bids.
Comparison: collection bid vs trait bid vs metadata bid
| Aspect | Collection bid | Trait bid | Metadata bid |
|---|---|---|---|
| Buy target | Any token in the collection | Any token whose attributes satisfy traitCriteria | Any token matching metadataId or metadataCriteria |
| Filter mechanism | None | Array of attribute filters | UUID or field-level filters spanning top-level metadata fields and attributes |
| Fulfillment validation | Token exists in collection | Token attributes satisfy all trait filters | Token metadata_id matches (id mode) or token metadata satisfies all field filters (criteria mode) |
| Typical use | Floor sweep / any item | Offers on attribute-filtered sets (e.g. legendary + blue) | Offers on tokens from a specific template (id mode) or on human-readable metadata conditions (criteria mode) |
Fees and cancellation
- Fees: same maker/taker concepts as other orders — see Fees.
- Cancel: use the bid’s order id with Cancel orders (soft or hard cancel patterns apply to open orders).
Next steps
Collection bids
Bids on any NFT in a collection without filters
Trait bids
Bids filtered by metadata trait attributes
Fill orders
Fulfillment, actions, and approvals
Cancel orders
Cancel metadata bids you created