Introduction
NFT collection trading data provides critical insights into market trends, asset valuations, and user activity. Developers, analysts, and traders rely on this information to make informed decisions. This guide explains how to use a dedicated API to fetch historical sales data for any NFT collection, including details like prices, platforms, and participant addresses.
Core Concepts: NFT Market Data
Before diving into the technical details, it's important to understand what constitutes NFT trading data. Each transaction on a blockchain is a record of an NFT's sale, containing a wealth of information. This data helps in analyzing market liquidity, collection popularity, and price fluctuations over time.
API Endpoint for NFT Trades
The primary method for retrieving this sales history is through a GET request to a specific endpoint.
- HTTP Method: GET
- Endpoint URL:
https://web3.okx.com/api/v5/mktplace/nft/markets/trades
Required and Optional Request Parameters
To successfully query the API, you must provide certain parameters. The table below outlines all available inputs for tailoring your data request.
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | String | Yes | The blockchain network name (e.g., Ethereum, Solana). |
collectionAddress | String | Yes | The smart contract address of the NFT collection. |
platform | String | No | The specific marketplace platform (e.g., OpenSea, LooksRare). Defaults to all platforms. |
limit | String | No | The number of records per page. Maximum is 50; default is 50. |
tokenId | String | No | The specific Token ID of an NFT within the collection. If empty, queries all tokens. |
cursor | String | No | A pagination cursor for retrieving the next page of results. |
startTime | String | No | The start time for the query's time range (Unix timestamp or ISO 8601). |
endTime | String | No | The end time for the query's time range (Unix timestamp or ISO 8601). |
Understanding Key Parameters
- Chain Specification: Accurately specifying the blockchain is crucial as collections exist on specific networks.
- Collection Address: This is the unique identifier for the group of NFTs you want to analyze. Using an incorrect address will result in errors or no data.
- Pagination: The
limitandcursorparameters are essential for handling large datasets efficiently, allowing you to browse through results page by page.
Interpreting the API Response
A successful API call returns a response containing an array of trade objects. Each object includes the following fields.
| Parameter | Type | Description |
|---|---|---|
cursor | String | The pagination cursor for the next page of results. |
amount | Integer | The number of NFTs traded in this specific transaction. |
chain | String | The blockchain network where the transaction occurred. |
collectionAddress | String | The smart contract address of the NFT collection. |
currencyAddress | String | The token address used for payment (e.g., ETH, WETH, USDC). |
from | String | The wallet address of the seller. |
to | String | The wallet address of the buyer. |
platform | String | The marketplace platform where the sale took place. |
price | BigDecimal | The price of a single NFT in the transaction. |
timestamp | Long | The Unix timestamp of when the transaction was confirmed. |
tokenId | String | The Token ID of the specific NFT that was sold. |
txHash | String | The on-chain transaction hash, serving as a unique proof of the trade. |
Step-by-Step Usage Guide
- Identify the Collection: Determine the exact smart contract address of the NFT collection and the blockchain it resides on.
- Formulate the Request: Construct your GET request, including the mandatory
chainandcollectionAddressparameters. - Refine Your Query: Use optional filters like
platform,tokenId, orstartTime/endTimeto narrow down the results to your specific needs. - Handle Pagination: For large collections, use the
cursorfrom the response to retrieve all historical data in manageable chunks. - Parse the Data: Extract and analyze the relevant fields from the JSON response for your application.
👉 Explore more strategies for analyzing NFT data
Common Applications for Trading Data
This API is versatile and supports various use cases:
- Market Analysis: Tracking floor price changes and sales volume for a collection.
- Portfolio Tracking: Monitoring the performance of owned NFTs.
- Trend Identification: Discovering which traits or specific NFTs are gaining value.
- Platform Comparison: Comparing sales activity across different marketplaces.
Frequently Asked Questions
What is the most important parameter for the NFT trades API?
The collectionAddress is the most critical parameter. Without the correct contract address for the NFT collection on the specified blockchain, the API will not return any relevant sales data. Always verify this address from a reliable source.
How can I fetch data for a single, specific NFT?
To get the transaction history for one particular NFT, you must provide both the collectionAddress and the exact tokenId of that NFT. This filters the results to show only sales involving that unique digital asset.
Why am I only getting 50 records back? How do I get more?
The API uses pagination to manage large data sets. The limit parameter caps results per page (max 50). To get more records, check the response for a cursor value and use it in your subsequent API request to retrieve the next page of results.
Can I analyze sales trends over a custom time period?
Yes, absolutely. Use the startTime and endTime parameters to define a specific time window for your query. This allows you to analyze market activity during particular events, seasons, or periods of high volatility.
What does the 'platform' field represent?
The platform field indicates which online marketplace facilitated the sale, such as OpenSea or Blur. This helps analysts understand which platforms are most popular for a given collection and if price differences exist between them.
Is the price returned in the native cryptocurrency?
The price is the sale amount, and the currencyAddress tells you which token was used for payment. This could be the native chain token (like ETH) or a stablecoin (like USDC). You must check the currencyAddress to know for sure.