This API interface returns all transaction records under a specific Ordinals collection, including comprehensive details about each transaction. The data is sorted in descending order by transaction time by default.
API Endpoint
Request Method: POST
Endpoint: https://web3.okx.com/api/v5/mktplace/nft/ordinals/trade-history
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| slug | String | Yes | Unique identifier of the collection (e.g., bitcoin-punks) |
| cursor | String | No | Pagination cursor for large datasets |
| limit | String | No | Number of records per page (default: 10, max: 100) |
| sort | String | No | Sort order (desc for descending, asc for ascending) |
| isBrc20 | Boolean | No | Filter by BRC-20 tokens (default: true) |
| orderSourceList | Integer[] | No | Platform codes (e.g., [34,54] for OKX/Magic Eden) |
| tradeWalletAddress | String | No | Wallet address involved in transactions |
| type | String | No | Transaction types (e.g., SALE,LIST) |
Response Parameters
Returns an array of Ordinals Activities Model objects with these fields:
| Field | Type | Description |
|---|---|---|
| fromAddress | String | Sender's wallet address |
| inscriptionId | String | Unique inscription ID (e.g., 12345abc) |
| price | String | Transaction price in BTC |
| timestamp | Long | Unix timestamp of transaction |
| toAddress | String | Receiver's wallet address |
| unitPrice | String | Price per unit (for bulk orders) |
| amount | String | Quantity of inscriptions transferred |
| isBrc20 | Boolean | true for BRC-20 tokens |
| orderSource | Integer | Platform code (e.g., 34 for OKX) |
| orderSourceName | String | Platform name (e.g., Magic Eden) |
| type | String | Transaction type (e.g., SALE) |
Example Use Cases
- Tracking NFT Sales: Monitor recent sales of a Bitcoin-based Ordinals collection.
- Wallet Activity Analysis: Retrieve all transactions involving a specific wallet address.
- BRC-20 Token Transactions: Filter transactions to only show BRC-20 token transfers.
FAQs
How do I handle pagination?
Use the cursor and limit parameters to navigate through large datasets. The API returns a nextCursor field in responses when more data is available.
Can I filter by transaction type?
Yes! Specify transaction types in the type parameter (e.g., type=SALE,LIST).
What's the difference between price and unitPrice?
price: Total transaction amountunitPrice: Price per item (relevant for bulk transactions)
Why isn't my wallet address returning data?
Ensure the address is correctly formatted and has participated in transactions for the specified collection.
👉 Get started with Ordinals API
Best Practices
- Set
limit=100for maximum efficiency when processing large datasets - Combine
isBrc20=falsewithorderSourceList=[54]to track Magic Eden's BTC NFT sales - Always verify timestamp freshness for real-time applications