> ## 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.

# Metadata bids

Place bids on NFTs in a collection that have a specific **metadata ID**. A metadata bid targets a group of tokens linked by the same metadata definition in Immutable's indexer.

<Info>
  See [Getting Started](/docs/products/orderbook/overview#getting-started) for prerequisites and installation.
</Info>

## 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** buy item.
* You attach a **`metadataId`**: a UUID that identifies a group of tokens sharing the same metadata definition in Immutable's [indexer](/docs/products/indexer/overview).
* **Matching semantics:** when a seller fills your bid with a specific `tokenId`, Immutable validates that the token's `metadata_id` in the indexer matches the `metadataId` on the bid.
* Orders appear as **`METADATA_BID`** in API responses alongside listings, bids, collection bids, and trait bids. Use the order `type` field when branching in your app or webhooks.

<Tip>
  If you want to filter by **individual trait attributes** (e.g. `Background` is `Blue`) rather than a metadata ID, use a **[trait bid](/docs/products/orderbook/trait-bids)** instead.
</Tip>

## Prerequisites

* Same setup as other orderbook flows ([Passport](/docs/products/passport/authentication) or wallet, [fees](/docs/products/orderbook/fees), etc.).
* **Metadata for fulfillment:** when a seller fills your bid with a specific `tokenId`, Immutable validates that token's **`metadata_id`** against the bid's `metadataId`. That requires the NFT metadata to be available through Immutable's [indexer](/docs/products/indexer/overview). If metadata is missing or the `metadata_id` does not match, fulfillment will fail.

## Creating a metadata bid

The flow mirrors [collection bids](/docs/products/orderbook/collection-bids): **prepare** (builds `orderComponents`, `orderHash`, and `actions`) → run any **approval** transactions → **sign** the EIP-712 order from the `SIGNABLE` action → **create**.

```typescript theme={null}
import { Orderbook, ActionType } from '@imtbl/orderbook';

const prepared = await orderbook.prepareMetadataBid({
  makerAddress: address,
  buy: {
    type: 'ERC721_COLLECTION',
    contractAddress: NFT_CONTRACT,
    amount: '1',
  },
  sell: {
    type: 'ERC20',
    contractAddress: PAYMENT_TOKEN,
    amount: '1000000000000000000', // wei
  },
});

// 1) Submit approval txs from prepared.actions (if any)
for (const action of prepared.actions) {
  if (action.type === ActionType.TRANSACTION) {
    const tx = await action.buildTransaction();
    await walletClient.sendTransaction(tx);
  }
}

// 2) Sign the CREATE_ORDER payload from the SIGNABLE action (EIP-712)
const signable = prepared.actions.find((a) => a.type === ActionType.SIGNABLE);
if (!signable) throw new Error('Missing signable order action');

const orderSignature = await walletClient.signTypedData({
  account: address,
  domain: signable.message.domain,
  types: signable.message.types,
  primaryType: 'OrderComponents',
  message: signable.message.value,
});

// 3) Create the metadata bid on Immutable
const { result } = await orderbook.createMetadataBid({
  orderComponents: prepared.orderComponents,
  orderHash: prepared.orderHash,
  orderSignature,
  makerFees: [],
  metadataId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', // UUID from the indexer
});

console.log('Metadata bid created:', result.id);
```

## Filling a metadata bid (seller)

Sellers call **`fulfillOrder`** 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.

```typescript theme={null}
import { Orderbook } from '@imtbl/orderbook';

const { actions } = await orderbook.fulfillOrder(
  metadataBidId,
  sellerAddress,
  [], // taker fees
  undefined, // amountToFill — omit for standard ERC-721 fills
  '123', // tokenId — required: the NFT the seller is selling into the bid
);

// Execute actions (approvals + fulfill) in order
for (const action of actions) {
  if (action.type === 'TRANSACTION') {
    const unsignedTx = await action.buildTransaction();
    const hash = await walletClient.sendTransaction(unsignedTx);
    await publicClient.waitForTransactionReceipt({ hash });
  }
}
```

<Warning>
  If the token's **`metadata_id`** in the indexer does not match the bid's `metadataId`, the orderbook will **not** return valid fulfillment data for that token.
</Warning>

For more context on actions, fees, and expiry, see [Fill orders](/docs/products/orderbook/fill-orders).

## Querying metadata bids

### List metadata bids

Filter by collection contract, status, maker, and pagination.

```typescript theme={null}
import { Orderbook, OrderStatusName } from '@imtbl/orderbook';

const { result, page } = await orderbook.listMetadataBids({
  buyItemContractAddress: NFT_CONTRACT,
  status: OrderStatusName.ACTIVE,
  pageSize: 50,
});

for (const bid of result) {
  console.log(bid.id, bid.metadataId, bid.sell.amount);
}
```

### Get one metadata bid

```typescript theme={null}
const { result: bid } = await orderbook.getMetadataBid(metadataBidId);

console.log({
  id: bid.id,
  status: bid.status,
  metadataId: bid.metadataId,
  sell: bid.sell,
  buy: bid.buy,
});
```

## 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 metadata matches `traitCriteria` | Any token whose `metadata_id` matches `metadataId`     |
| **Filter mechanism**       | None                        | Array of trait type/value filters                | Single metadata ID (UUID)                              |
| **Fulfillment validation** | Token exists in collection  | Token attributes satisfy all trait filters       | Token `metadata_id` matches bid                        |
| **Typical use**            | Floor sweep / any item      | Offers on filtered sets (e.g. legendary + blue)  | Offers on tokens from a specific template or blueprint |

## Fees and cancellation

* **Fees:** same maker/taker concepts as other orders — see [Fees](/docs/products/orderbook/fees).
* **Cancel:** use the bid's order id with [Cancel orders](/docs/products/orderbook/cancel-orders) (soft or hard cancel patterns apply to open orders).

## Next steps

<CardGroup cols={2}>
  <Card title="Collection bids" icon="gavel" href="/docs/products/orderbook/collection-bids">
    Bids on any NFT in a collection without filters
  </Card>

  <Card title="Trait bids" icon="filter" href="/docs/products/orderbook/trait-bids">
    Bids filtered by metadata trait attributes
  </Card>

  <Card title="Fill orders" icon="cart-shopping" href="/docs/products/orderbook/fill-orders">
    Fulfillment, actions, and approvals
  </Card>

  <Card title="Cancel orders" icon="xmark" href="/docs/products/orderbook/cancel-orders">
    Cancel metadata bids you created
  </Card>
</CardGroup>