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

# Collection Bids

Place bids on **any** NFT within a collection, rather than a specific token. Useful for buyers who want to acquire any item from a collection at a certain price.

> [!NOTE]
>
> See [Getting Started](https://docs.immutable.com/docs/products/orderbook/overview.md#getting-started) for prerequisites and installation.

> [!TIP]
>
> Need to target **only NFTs whose metadata matches certain traits** (for example, `Background` is `Blue` or `Red`)? Use a **[trait bid](https://docs.immutable.com/docs/products/orderbook/trait-bids.md)** instead: same criteria-style collection offer, but Immutable validates the seller’s `tokenId` against your trait filters at fulfillment time.

## Creating a Collection Bid

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

const prepared = await orderbook.prepareCollectionBid({
  makerAddress: address,
  buy: {
    type: 'ERC721_COLLECTION',
    contractAddress: NFT_CONTRACT,
    amount: '1', // Bidding on 1 NFT from the collection
  },
  sell: {
    type: 'ERC20',
    contractAddress: '0x...', // IMX ERC20 token address
    amount: '500000000000000000', // Offering 0.5 IMX
  },
});

for (const action of prepared.actions) {
  if (action.type === ActionType.TRANSACTION) {
    const tx = await action.buildTransaction();
    await walletClient.sendTransaction(tx);
  }
}

const signable = prepared.actions.find((a) => a.type === ActionType.SIGNABLE)!;
const signature = await walletClient.signTypedData({
  account: address,
  domain: signable.message.domain,
  types: signable.message.types,
  primaryType: 'OrderComponents',
  message: signable.message.value,
});

const { result } = await orderbook.createCollectionBid({
  orderComponents: prepared.orderComponents,
  orderHash: prepared.orderHash,
  orderSignature: signature,
  makerFees: [],
});

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

## Bidding on Multiple NFTs

Bid on multiple items from a collection in a single order:

```typescript theme={null}
const preparedMulti = await orderbook.prepareCollectionBid({
  makerAddress: address,
  buy: {
    type: 'ERC721_COLLECTION',
    contractAddress: NFT_CONTRACT,
    amount: '5', // Bidding on 5 NFTs
  },
  sell: {
    type: 'ERC20',
    contractAddress: '0x...', // IMX ERC20 token address
    amount: '2500000000000000000', // 0.5 IMX each = 2.5 IMX total
  },
});
// Then sign `preparedMulti.actions` and call `createCollectionBid` the same way as the single-NFT example above.
```

## Accepting Collection Bids (Sellers)

Sellers can fill collection bids by selecting which token to sell:

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

// Fulfill a collection bid with a specific token (5th argument is tokenId for criteria-based orders)
const { actions } = await orderbook.fulfillOrder(
  collectionBidId,
  `sellerAddress`,
  [], // taker fees
  undefined, // amountToFill — omit for ERC-721 collection fills
  '123', // tokenId — specific token the seller is selling into the bid
);

// Execute all required actions
for (const action of actions) {
  if (action.type === 'TRANSACTION') {
    const unsignedTx = await action.buildTransaction();
    const hash = await walletClient.sendTransaction(unsignedTx);
    await publicClient.waitForTransactionReceipt({ hash });
  }
}
```

## Querying Collection Bids

### List Collection Bids for a Contract

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

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

for (const bid of result) {
  const pricePerItem = BigInt(bid.sell.amount) / BigInt(bid.buy.amount);
  console.log(`Bid for ${bid.buy.amount} NFTs at ${pricePerItem} IMX each`);
}
```

### Get Best Collection Bid

Find the highest offer for any NFT in a collection:

> [tab] TypeScript
>
> ```typescript theme={null}
> const { result } = await orderbook.listCollectionBids({
>   buyItemContractAddress: NFT_CONTRACT,
>   status: OrderStatusName.ACTIVE,
>   sortBy: 'sell_item_amount',
>   sortDirection: 'desc',
>   pageSize: 1,
> });
>
> if (result.length > 0) {
>   console.log('Best collection bid:', result[0].sell.amount, 'IMX');
> }
> ```

## Use Cases

| Scenario | Implementation |
| - | - |
| **Floor sweeping** | Bid on multiple NFTs at floor price |
| **Portfolio building** | Acquire any item from desired collections |
| **Arbitrage** | Bid below market value across collections |
| **Instant liquidity** | Sellers can instantly sell to highest bidder |

## Comparison: Token Bids vs Collection Bids vs Trait Bids

| Aspect | Token Bid | Collection Bid | Trait bid |
| - | - | - | - |
| **Target** | Specific token ID | Any token in collection | Tokens in collection whose **metadata** matches [trait filters](https://docs.immutable.com/docs/products/orderbook/trait-bids.md) |
| **Use case** | Want one known asset | Want any item from the collection | Want items matching attributes (e.g. rarity + background) |
| **Fill flexibility** | Only that token can fill | Seller chooses which token | Seller chooses `tokenId`; must satisfy trait criteria |
| **Price discovery** | Token-level | Collection-level | Filtered subset of collection |

## Next Steps

> [card] [Create Listings](https://docs.immutable.com/docs/products/orderbook/create-listings.md)
>
> Alternative: Sell NFTs via listings

> [card] [Fill Orders](https://docs.immutable.com/docs/products/orderbook/fill-orders.md)
>
> Sellers: Accept collection bids

> [card] [Cancel Orders](https://docs.immutable.com/docs/products/orderbook/cancel-orders.md)
>
> Cancel collection bids (soft/hard)

> [card] [Order Management](https://docs.immutable.com/docs/products/orderbook/order-management.md)
>
> Query and track your bids

> [card] [Trait bids](https://docs.immutable.com/docs/products/orderbook/trait-bids.md)
>
> Bids constrained by NFT metadata traits

> [card] [Metadata bids](https://docs.immutable.com/docs/products/orderbook/metadata-bids.md)
>
> Bids matched by metadata ID or field-level metadata criteria


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.