Retrieve Ordinals Activities Using the Ordinals API

Accessing detailed transaction data for Bitcoin-based digital assets has never been easier. Whether you're a developer building a Web3 application, a collector tracking NFT movements, or a marketplace analyzing trade trends, retrieving accurate and timely Ordinals activities is essential. This guide explores how to use the Ordinals API to fetch comprehensive trade history for any collection on the Bitcoin blockchain.

The interface described here returns all transaction records associated with a specific collection. Each record includes critical details such as sender (fromAddress) and receiver (toAddress) addresses, transaction timestamps, pricing information, and more. By default, results are sorted in descending order by transaction time—ensuring you always get the most recent activity first.

This functionality is part of the broader Marketplace API suite offered through WaaS (Web3 as a Service), empowering developers with scalable tools to integrate blockchain data seamlessly into their applications.

How to Request Ordinals Trade History

To retrieve transaction data, send a POST request to the following endpoint:

https://web3.okx.com/api/v5/mktplace/nft/ordinals/trade-history

This endpoint supports multiple filtering and pagination options, allowing you to customize your query based on your application’s needs.

👉 Discover powerful blockchain data tools that enhance your Web3 development workflow.

Request Parameters

You can fine-tune your request using the following parameters:

• slug (String, required)
  The unique identifier (slug) of the collection whose trade history you want to retrieve.
• cursor (String, optional)
  Used for pagination. Points to the specific page of results you wish to fetch.
• limit (String, optional)
  Sets the maximum number of records returned per request. Default is 10; maximum allowed is 100.
• sort (String, optional)
  Controls the sort order of results. Default is desc (descending by timestamp), but you can also use asc for ascending order.
• isBrc20 (Boolean, optional)
  Determines whether to retrieve trade activities for BTC NFTs or BRC-20 tokens. Default behavior retrieves BTC NFT activity.

• orderSourceList (Integer[], optional)
  Filter results by marketplace source using platform codes:

  • 34: OKX
  • 54: Magic Eden
  • 55: OrdinalsWallet
  • 57: Unisat
    Example: [34, 54] returns trades from both OKX and Magic Eden.
• tradeWalletAddress (String, optional)
  Restrict results to transactions involving a specific wallet address.
• type (String, optional)
  Filter by transaction type. Accepts comma-separated values:
  SALE, LIST, TRANSFER, CANCEL_LIST, UPDATE_PRICE.
  If not specified, only SALE transactions are returned by default.

Understanding the Response Data

The API returns an array of Ordinals Activities objects, each representing a single transaction event. Here's what each field means:

• fromAddress (String)
  The wallet address sending the inscription.
• inscriptionId (String)
  Unique identifier for the Bitcoin inscription involved in the transaction.
• price (String)
  Total price paid for the inscription, denominated in BTC.
• timestamp (Long)
  Unix timestamp indicating when the transaction occurred.
• toAddress (String)
  The receiving wallet address.
• unitPrice (String)
  Unit price per inscription in BTC—useful when multiple inscriptions are transferred in bulk.
• amount (String)
  Number of inscriptions included in the transaction.
• isBrc20 (Boolean)
  Indicates whether the inscription is a BRC-20 token (true) or a standard BTC NFT (false).
• orderSource (Integer)
  Numeric code identifying the platform where the trade took place.
• orderSourceName (String)
  Human-readable name of the marketplace (e.g., "OKX", "Magic Eden").
• type (String)
  Type of transaction: SALE, LIST, TRANSFER, etc.

This structured response enables developers to build rich analytics dashboards, track wallet activity, monitor floor prices, and much more.

Practical Use Cases for Developers

Real-Time Market Monitoring

Build live-updating market trackers that display recent sales, price trends, and volume spikes across major platforms like OKX and Magic Eden.

Wallet Activity Auditing

Enable users to audit their own or public wallet histories by pulling all associated Ordinals transactions in chronological order.

Collection Analytics Tools

Create dashboards that visualize key metrics such as average sale price, trading volume over time, and top marketplaces for a given collection.

👉 Unlock real-time blockchain insights with reliable Web3 APIs designed for developers.

Frequently Asked Questions (FAQ)

What is the default sorting order for trade history?

By default, transaction records are sorted in descending order by timestamp, meaning the most recent trades appear first in the response list.

Can I filter transactions by multiple types at once?

Yes. You can specify multiple transaction types in the type parameter by separating them with commas. For example: SALE,TRANSFER,CANCEL_LIST.

How do I paginate through large datasets?

Use the cursor parameter along with limit to navigate through pages of results. The API response will typically include a cursor for the next page if additional data is available.

Is there a rate limit for this API endpoint?

While specific rate limits aren’t detailed here, it’s recommended to implement throttling in your application to avoid excessive requests. For production use, consider caching responses or using webhooks where available.

Can I retrieve BRC-20 token trades using this API?

Yes. Set the isBrc20 parameter to true to specifically fetch BRC-20 related transaction activities. Otherwise, BTC NFT trades are returned by default.

Does the API support cross-marketplace filtering?

Absolutely. Use the orderSourceList parameter with an array of platform codes (e.g., [34,54]) to retrieve trades only from selected marketplaces like OKX or Magic Eden.

Core Keywords Summary

This guide integrates the following core keywords naturally throughout the content to align with search intent and improve SEO performance:

• Ordinals API
• Retrieve Ordinals activities
• Marketplace API
• WaaS Web3 API
• Bitcoin NFT transactions
• BRC-20 trade history
• NFT trade data
• Blockchain transaction API

These terms reflect common queries from developers and analysts seeking reliable access to on-chain Ordinals data.

👉 Start integrating high-performance Web3 APIs today and accelerate your project development.

By leveraging this powerful API endpoint, developers gain direct access to granular, real-time transaction data across leading Bitcoin NFT and BRC-20 marketplaces. With flexible filtering, clear response structures, and support for pagination and sorting, it's an indispensable tool for anyone building in the evolving Web3 ecosystem.