Skip to main content

​
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 metadata_id / metadataId (for id-mode bids) or metadata_criteria / metadataCriteria (for criteria-mode bids). Exactly one of those two fields is populated per metadata bid.

​
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 exactly one of metadata_id or metadata_criteria, depending on how the bid was created. 
// metadata_id mode
{
  "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" }]
  }
}

// metadata_criteria mode
{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "metadata-bid-790",
    "status": "ACTIVE",
    "type": "METADATA_BID",
    "metadata_criteria": [
      { "field_name": "name", "values": ["Cool Dragon"] },
      { "field_name": "attribute:Background", "values": ["Blue", "Red"] }
    ],
    "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 or field-criteria metadata bids