The OKX Runes API provides developers and marketplace operators with a powerful interface to retrieve specific collection listing information from the OKX Runes platform. This Web3 service allows for efficient querying of NFT listings using the unique runesId identifier, supporting various sorting and pagination parameters to tailor the data retrieval process to specific needs.
API Request Structure
Request Address
The API endpoint for accessing Runes listing data is a GET request to the following URL:https://web3.okx.com/api/v5/mktplace/nft/runes/get-runes-order-list
Essential Request Parameters
To successfully query the Runes API, you need to include specific parameters in your request:
- runesId (String, Required): The unique identifier for the Runes token you wish to query
- cursor (String, Optional): A pointer to the sorting sequence for pagination (maximum 1,000 records)
- limit (Integer, Optional): Determines the page size for results (default: 10, maximum: 100)
sortBy (String, Optional): Specifies the ordering of results with these available options:
- unitPriceAsc (ascending unit price)
- unitPriceDesc (descending unit price)
- totalPriceAsc (ascending total price)
- totalPriceDesc (descending total price)
- listedTimeAsc (ascending listing time)
- listedTimeDesc (descending listing time)
Comprehensive Response Parameters
The API returns detailed information about each Runes listing, organized into several categories:
Asset Identification Data
- assetId: Database primary key identifier
- tickerType: Token type (4 represents Runes)
- ticker: Token name
- tickerId: Unique token identifier
Ownership and Blockchain Information
- ownerAddress: Wallet address of the current owner
- amount: XRC20 amount contained in the UTXO
- chain: Blockchain network identifier
- inscriptionNum: The inscription number on the blockchain
- utxoTxHash: Transaction hash of the UTXO
- utxoVout: UTXO output index
- utxoValue: Value contained in the UTXO
Transaction and Status Details
- txHash: Transaction hash
- name: Token name
- tickerIcon: URL link to the token's icon
- status: Current listing status (0-unlisted, 1-listed, 2-pending)
- listTime: Timestamp of when the item was listed
- orderId: Unique identifier for the order
- confirmations: Block height confirmation information
- unavailable: Indicator if UTXO contains multiple assets (1-multiple Atomicals, 2-multiple protocol assets)
- symbol: Trading symbol
Pricing Information
The API provides comprehensive pricing data in multiple formats and currencies:
Total Price Fields:
- Currency type and corresponding URL
- Price in satoshis
- Price in BTC
- Price in USD
Unit Price Fields:
- Currency type and corresponding URL
- Price per unit in satoshis
- Price per unit in BTC
- Price per unit in USD
Practical Implementation Guide
When implementing the OKX Runes API in your application, consider these best practices:
Start with the required runesId parameter to ensure you're querying the correct collection. Use pagination parameters (cursor and limit) to manage large datasets efficiently, especially when dealing with popular collections that may have hundreds of listings.
The sorting options allow you to display listings according to user preferences. For example, traders looking for bargains might prefer unitPriceAsc, while those seeking premium items might choose unitPriceDesc.
👉 Explore more strategies for API implementation
Common Use Cases and Applications
The Runes API serves various purposes in the Web3 ecosystem:
Marketplace Integration: Platform developers can integrate real-time Runes listing data directly into their marketplaces, providing users with up-to-date information without leaving their platform.
Portfolio Tracking: Developers can create portfolio management tools that track the current market value of users' Runes collections by querying listing prices and availability.
Arbitrage Opportunities: Traders can use the API to identify price discrepancies across different marketplaces or within the same collection.
Data Analysis: Researchers and analysts can collect historical listing data to identify market trends, trading patterns, and valuation metrics for specific Runes collections.
Frequently Asked Questions
What is the primary purpose of the OKX Runes API?
The OKX Runes API allows developers to retrieve detailed listing information for Runes tokens on the OKX marketplace. It provides comprehensive data including pricing, ownership details, and transaction information, enabling integration with various Web3 applications and services.
How do I handle pagination with the Runes API?
Use the cursor parameter in conjunction with the limit parameter to manage pagination. The cursor points to your current position in the result set, and you can adjust the limit to control how many records are returned per request, making it efficient to browse through large collections.
What different sorting options are available?
The API supports six sorting methods: by unit price (ascending/descending), by total price (ascending/descending), and by listing time (ascending/descending). This flexibility allows you to organize listings based on different user preferences or analytical needs.
How current is the listing information provided by the API?
The API provides real-time or near-real-time data from the OKX marketplace, ensuring that the listing information reflects the current state of the market. The listTime parameter specifically indicates when each item was listed for sale.
What should I do if I encounter multiple assets in a UTXO?
The unavailable parameter indicates when a UTXO contains multiple assets (value 1 for multiple Atomicals, value 2 for multiple protocol assets). In such cases, you may need additional processing to handle these complex transactions appropriately.
Are there rate limits or restrictions on API usage?
While the documentation doesn't specify exact rate limits, it's good practice to implement reasonable request intervals and error handling for rate limit responses. Always check the latest API documentation for any usage restrictions or best practices.
Best Practices for API Integration
When working with the OKX Runes API, consider implementing these strategies:
Always include proper error handling for API requests, as network conditions and server availability can vary. Implement caching mechanisms where appropriate to reduce redundant requests and improve application performance.
Use the comprehensive pricing data to provide users with multiple valuation perspectives (BTC, USD, and satoshis). This multi-currency approach caters to different user preferences and trading strategies.
Leverage the sorting capabilities to enhance user experience. For example, you might implement default sorting based on user behavior or preferences, or allow users to switch between different sorting methods dynamically.
👉 Get advanced methods for API optimization
Conclusion
The OKX Runes API offers a robust solution for accessing detailed listing information from the OKX Runes marketplace. With comprehensive parameters for filtering, sorting, and paginating results, along with extensive response data covering ownership, pricing, and transaction details, this API provides everything developers need to build sophisticated Web3 applications.
Whether you're creating a marketplace interface, portfolio tracker, or analytical tool, the API's structured data and flexible query options make it an invaluable resource for anyone working with Runes tokens in the Web3 ecosystem.