Query Listings: Order API for NFT Marketplaces

Navigating the dynamic world of NFT trading requires reliable, real-time data access—especially when monitoring active listings across decentralized marketplaces. The Query Listings API offered by OKX enables developers and traders to retrieve detailed information about active NFT orders built on the Seaport protocol. Whether you're building a marketplace dashboard, tracking price trends, or automating trade decisions, this API delivers structured, filterable data to power your Web3 applications.

This guide breaks down the functionality, parameters, and use cases of the Query Listings endpoint, helping you integrate it efficiently into your workflow while optimizing for performance and accuracy.

What Is the Query Listings API?

The Query Listings API is a GET endpoint that returns a list of valid NFT listings created via the Seaport protocol on supported blockchains. It allows users to fetch current buy-now or offer orders based on customizable filters such as collection address, token ID, price range, and order status.

This API is part of OKX’s broader Wallet-as-a-Service (WaaS) offering, which provides developers with scalable Web3 infrastructure tools for building decentralized applications (dApps), NFT market aggregators, and analytics platforms.

👉 Discover how powerful API tools can enhance your NFT trading strategy.

Endpoint Details

Request URL

GET https://web3.okx.com/api/v5/mktplace/nft/markets/listings

This RESTful endpoint supports query parameters to refine results and paginate large datasets efficiently.

Request Parameters

You can customize your request using the following optional and required parameters:

• chain (String, Required): Specifies the blockchain network (e.g., Ethereum, Arbitrum). See supported chains for full details.
• collectionAddress (String, Optional): Filters results by NFT contract address.
• tokenId (String, Optional): Returns listings for a specific NFT token ID.
• maker (String, Optional): Filters orders by the wallet address of the seller or bidder.
• createAfter / createBefore (String, Optional): Restricts results to orders created within a timestamp range (in seconds).
• updateAfter / updateBefore (String, Optional): Filters by last update time of the order.

• status (String, Optional): Filters by order status. Accepts:

  • active
  • inactive
  • cancelled
  • sold
• platform (String, Optional): Targets specific marketplaces (e.g., OKX NFT Marketplace). Default: okx.

• sort (String, Optional): Defines sorting logic:

  • create_time_desc: Newest first by creation time
  • update_time_desc: Most recently updated first
  • price_desc: Highest price first
  • price_asc: Lowest price first
    Default: chronological order.
• limit (String, Optional): Number of records per page. Default: 50.
• cursor (String, Optional): Pagination cursor for retrieving subsequent pages.

These parameters allow granular control over data retrieval—ideal for building responsive UIs or analyzing market behavior.

Response Structure

The API returns an array of Order Model objects conforming to the OKX Order Schema, with the following key fields:

• orderId: Unique identifier for the order.
• createTime: Timestamp (in milliseconds) when the order was created.
• updateTime: Last update timestamp.
• listingTime: Time the item was listed for sale.
• expirationTime: When the listing expires (epoch time).
• status: Current state of the order (active, cancelled, sold, inactive).
• orderHash: Cryptographic hash representing the order on-chain.
• protocolData: JSON string containing full Seaport order parameters.
• protocolAddress: Smart contract address handling the trade execution.
• chain: Network where the listing exists.
• maker: Wallet address initiating the order.
• orderType: Either Offer (bid) or BuyNow (direct sale).
• price: Price per NFT in the listed currency.
• currencyAddress: Token contract address used for payment (e.g., WETH, USDC).
• collectionAddress: NFT collection contract.
• tokenId: Identifier of the NFT within the collection.
• amount: Quantity of NFTs listed (relevant for ERC-1155 tokens).

This structured format ensures compatibility with frontend displays, backend processing, and cross-market analysis tools.

Practical Use Cases

1. NFT Floor Price Monitoring

By fetching all active BuyNow listings for a given collection and sorting by price_asc, you can calculate the current floor price in real time—critical for traders and portfolio trackers.

2. Automated Bid Tracking

Filtering by orderType=Offer and a specific maker allows bots or personal dashboards to monitor outgoing bids across platforms.

3. Marketplace Aggregation

Developers can pull listings from multiple collections and chains, then normalize and display them in a unified interface—similar to how NFT explorers like OpenSea or Blur operate.

4. Historical Listing Analysis

Using time-range filters (createAfter, updateAfter), analysts can study listing volume trends, average sale times, or seller behavior over periods.

👉 Explore real-time NFT data with advanced API access today.

Frequently Asked Questions

Q: Can I query listings for both ERC-721 and ERC-1155 tokens?
A: Yes. The API supports both standards. For ERC-1155, the amount field indicates how many copies are being sold.

Q: How often is listing data updated?
A: Data is synchronized in near real-time from on-chain events and indexer updates. Delays are typically under 15 seconds.

Q: Is there a rate limit for this API?
A: Rate limits depend on your authentication level and plan type under OKX WaaS. Unauthenticated calls may be throttled; authenticated users receive higher quotas.

Q: What does “cursor-based pagination” mean?
A: Instead of page numbers, each response includes a cursor pointing to the next dataset. Use the cursor parameter in subsequent requests to fetch more results seamlessly.

Q: How do I distinguish between bids and direct sales?
A: Check the orderType field: Offer means it’s a bid; BuyNow indicates a fixed-price listing.

Q: Can I get historical sold prices using this endpoint?
A: No. This endpoint only returns listings. For transaction history, use the separate Trades or Sales API.

Best Practices for Integration

• Always specify the chain parameter to avoid ambiguous results.
• Use limit and cursor together for efficient pagination—avoid requesting more than 100 items at once.
• Cache responses client-side where appropriate to reduce redundant calls.
• Validate timestamps before sending date-based filters to prevent empty responses.
• Monitor changes in status and updateTime to detect cancellations or sales.

For production-grade applications, consider pairing this with webhooks or WebSocket streams (if available) to react instantly to new listings.

Final Thoughts

The Query Listings API is a foundational tool for anyone working in the NFT space—from developers building next-gen dApps to traders seeking an edge through data. Its flexibility, rich filtering options, and standardized output make it ideal for integration into analytics platforms, portfolio managers, and automated trading systems.

As NFT markets continue evolving, having direct access to raw order book data empowers innovation and transparency across the ecosystem.

👉 Unlock advanced NFT data capabilities with OKX's developer suite.