Skip to main content
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.

​
Creating a Collection Bid

import { Orderbook } from '@imtbl/orderbook';

// Prepare a collection bid
const { orderComponents, orderHash, typedData } = 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
  },
});

// Sign the bid (gasless)
const signature = await walletClient.signTypedData({
  account: address,
  ...typedData,
});

// Submit the bid
const { result } = await orderbook.createCollectionBid({
  orderComponents,
  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 { orderComponents, orderHash, typedData } = 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
  },
});

​
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
const { actions } = await orderbook.fulfillOrder(
  collectionBidId,
  `sellerAddress`,
  [], // taker fees
  {
    tokenId: '123', // Specific token to sell
  }
);

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

ScenarioImplementation
Floor sweepingBid on multiple NFTs at floor price
Portfolio buildingAcquire any item from desired collections
ArbitrageBid below market value across collections
Instant liquiditySellers can instantly sell to highest bidder

​
Comparison: Token Bids vs Collection Bids

AspectToken BidCollection Bid
TargetSpecific token IDAny token in collection
Use caseWant specific traits/rarityWant any item
Fill flexibilityOnly that token can fillSeller chooses which token
Price discoveryToken-levelCollection-level

​
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