Skip to main content

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.

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: 
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 vs Trait Bids

AspectToken BidCollection BidTrait bid
TargetSpecific token IDAny token in collectionTokens in collection whose metadata matches trait filters
Use caseWant one known assetWant any item from the collectionWant items matching attributes (e.g. rarity + background)
Fill flexibilityOnly that token can fillSeller chooses which tokenSeller chooses tokenId; must satisfy trait criteria
Price discoveryToken-levelCollection-levelFiltered 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 on tokens sharing a specific metadata ID