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.

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: 'NATIVE',
    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: 'NATIVE',
    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 hash = await walletClient.sendTransaction({
      to: action.to,
      data: action.data,
    });
    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