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.

See Getting Started for prerequisites and installation.

Need to target only NFTs whose metadata matches certain traits (for example, Background is Blue or Red)? Use a trait bid instead: same criteria-style collection offer, but Immutable validates the seller’s tokenId against your trait filters at fulfillment time.

Creating a Collection Bid

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:

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:

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

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:

TypeScript

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

Create Listings

Alternative: Sell NFTs via listings

Fill Orders

Sellers: Accept collection bids

Cancel Orders

Cancel collection bids (soft/hard)

Order Management

Query and track your bids

Trait bids

Bids constrained by NFT metadata traits

Metadata bids

Bids matched by metadata ID or field-level metadata criteria

PRODUCTS

GUIDES

Creating a Collection Bid

Bidding on Multiple NFTs

Accepting Collection Bids (Sellers)

Querying Collection Bids

List Collection Bids for a Contract

Get Best Collection Bid

Use Cases

Comparison: Token Bids vs Collection Bids vs Trait Bids

Next Steps

Create Listings

Fill Orders

Cancel Orders

Order Management

Trait bids

Metadata bids

​Creating a Collection Bid

​Bidding on Multiple NFTs

​Accepting Collection Bids (Sellers)

​Querying Collection Bids

​List Collection Bids for a Contract

​Get Best Collection Bid

​Use Cases

​Comparison: Token Bids vs Collection Bids vs Trait Bids

​Next Steps

Create Listings

Fill Orders

Cancel Orders

Order Management

Trait bids

Metadata bids

Creating a Collection Bid

Bidding on Multiple NFTs

Accepting Collection Bids (Sellers)

Querying Collection Bids

List Collection Bids for a Contract

Get Best Collection Bid

Use Cases

Comparison: Token Bids vs Collection Bids vs Trait Bids

Next Steps