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.

​
Querying Orders

​
Get a Single Order

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

const { result: order } = await orderbook.getListing(orderId);

console.log({
  id: order.id,
  status: order.status,
  price: order.buy.amount,
  seller: order.accountAddress,
  tokenId: order.sell.tokenId,
});

​
List Orders for a Collection

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

const { result } = await orderbook.listListings({
  sellItemContractAddress: NFT_CONTRACT,
  status: OrderStatusName.ACTIVE,
  pageSize: 50,
});

for (const listing of result) {
  console.log(`Token #${listing.sell.tokenId}: ${listing.buy.amount} IMX`);
}

​
Pagination

let cursor: string | undefined;

do {
  const { result, page } = await orderbook.listListings({
    sellItemContractAddress: NFT_CONTRACT,
    status: OrderStatusName.ACTIVE,
    pageSize: 100,
    pageCursor: cursor,
  });
  
  for (const listing of result) {
    console.log(listing.id);
  }
  
  cursor = page.nextCursor;
} while (cursor);

​
Order Status

For complete order status definitions and lifecycle, see Order Lifecycle.

​
Fill Status

For fill status details and tracking partial fills, see Fill Orders: Fill Status.

​
Cancelling Orders

For detailed cancellation methods, race conditions, and best practices, see Cancel Orders.

​
Webhooks

Get real-time notifications for order events. Configure webhooks in Hub. For implementation details, see the webhook documentation.
EventTrigger
imtbl_order_updatedOrder status changed
imtbl_activity_saleTrade completed
Webhook payloads can represent listings, bids, collection bids, trait bids, or metadata bids. Use the order type field (and related discriminator fields your integration already uses) to branch—for example, handle TRAIT_BID when you need to read trait_criteria / traitCriteria for display or analytics, or handle METADATA_BID when you need to read the metadata_id / metadataId.

​
Webhook Payload Example

{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "order-123",
    "status": "FILLED",
    "type": "LISTING",
    "sell": {
      "type": "ERC721",
      "contract_address": "0x...",
      "token_id": "456"
    },
    "buy": {
      "type": "NATIVE",
      "amount": "1000000000000000000"
    }
  }
}
Trait bid payloads include the same high-level sell / buy / status fields and add trait criteria 
{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "trait-bid-456",
    "status": "ACTIVE",
    "type": "TRAIT_BID",
    "trait_criteria": [
      { "trait_type": "Background", "values": ["Blue", "Red"] }
    ],
    "sell": [{ "type": "ERC20", "contract_address": "0x...", "amount": "1000000000000000000" }],
    "buy": [{ "type": "ERC721_COLLECTION", "contract_address": "0xnft...", "amount": "1" }]
  }
}
Metadata bid payloads include the same high-level sell / buy / status fields and add a metadata_id 
{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "metadata-bid-789",
    "status": "ACTIVE",
    "type": "METADATA_BID",
    "metadata_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sell": [{ "type": "ERC20", "contract_address": "0x...", "amount": "1000000000000000000" }],
    "buy": [{ "type": "ERC721_COLLECTION", "contract_address": "0xnft...", "amount": "1" }]
  }
}

​
Next Steps

Create Listings

Learn how to create NFT listings

Fill Orders

Buy NFTs by filling orders

Cancel Orders

Cancel listings with soft or hard cancels

Fees

Understand fee structure and calculations

Trait bids

Create and query metadata-filtered collection bids

Metadata bids

Create and query metadata ID-based collection bids