> ## 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.
See [Getting Started](/docs/products/orderbook/overview#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](/docs/products/orderbook/trait-bids)** 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:
```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](/docs/products/orderbook/trait-bids) |
| **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
Alternative: Sell NFTs via listings
Sellers: Accept collection bids
Cancel collection bids (soft/hard)
Query and track your bids
Bids constrained by NFT metadata traits
Bids on tokens sharing a specific metadata ID