The Runes API provides a powerful and efficient way to retrieve detailed listing information for specific Runes tokens on the OKX marketplace. By utilizing this API, developers and traders can programmatically access real-time data on asset listings, including pricing, status, and ownership details. This guide will walk you through the essential components of the API, from the request structure to the response parameters, ensuring you can integrate it seamlessly into your applications.
Understanding the Runes API Endpoint
The core functionality of this API revolves around the GET request method. The designated endpoint for retrieving Runes listings is:
https://web3.okx.com/api/v5/mktplace/nft/runes/get-runes-order-listThis endpoint is specifically designed to fetch order list data for a given Runes token identified by its unique runesId.
Required and Optional Request Parameters
To successfully query the API, you must include specific parameters in your request. The following table outlines all available parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| runesId | String | Yes | The unique identifier for the Runes token. |
| cursor | String | No | A cursor for pagination, pointing to the specific sorting sequence to retrieve data from (maximum of 1,000 records). |
| limit | Integer | No | The number of orders to return per page. The default value is 10, and the maximum allowed value is 100. |
| sortBy | String | No | The rule for sorting the orders. The default is unitPriceAsc. Other options include unitPriceDesc, totalPriceAsc, totalPriceDesc, listedTimeAsc, and listedTimeDesc. |
The runesId is the only mandatory parameter. The others allow you to control the volume and order of the data returned, which is essential for managing large datasets and user experience.
Interpreting the API Response
A successful API call returns a wealth of information about the listed Runes tokens. The response is formatted in JSON and contains the following parameters:
| Parameter | Type | Description |
|---|---|---|
| assetId | Integer | A database primary key identifier. |
| tickerType | String | Indicates the token type (e.g., "4" for Runes). |
| ticker | Integer | The name of the token. |
| tickerId | String | The unique token ID. |
| ownerAddress | String | The wallet address of the current owner. |
| amount | String | The XRC20 amount present in the UTXO. |
| chain | Integer | The blockchain on which the token resides. |
| inscriptionNum | String | The inscription number associated with the token. |
| utxoTxHash | String | The transaction hash of the UTXO. |
| utxoVout | Integer | The output index of the UTXO. |
| utxoValue | String | The value of the UTXO. |
| txHash | String | The transaction hash. |
| name | String | The name of the token. |
| tickerIcon | String | A URL link to the token's icon image. |
| status | Integer | The current listing status (0: unlisted, 1: listed, 2: pending). |
| listTime | Long | The timestamp of when the token was listed. |
| orderId | Long | The unique identifier for the listing order. |
| confirmations | Long | The number of block confirmations. |
| currency | String | The currency used for the total price. |
| currencyUrl | String | A URL associated with the currency. |
| satPrice | BigDecimal | The total price denominated in satoshis. |
| price | BigDecimal | The total price denominated in BTC. |
| usdPrice | BigDecimal | The total price denominated in US Dollars. |
| currency | String | The currency used for the unit price. |
| currencyUrl | String | A URL associated with the unit price currency. |
| satPrice | BigDecimal | The unit price denominated in satoshis. |
| price | BigDecimal | The unit price denominated in BTC. |
| usdPrice | BigDecimal | The unit price denominated in US Dollars. |
| unavailable | Integer | Indicates if the UTXO contains multiple assets (1 for multiple Atomicals, 2 for multiple protocol assets). |
| symbol | String | The symbol representing the token. |
This detailed response allows for comprehensive analysis of each listed asset, enabling informed trading and portfolio management decisions. 👉 Explore more strategies for analyzing market data
Practical Implementation and Use Cases
Integrating the Runes API into your workflow can significantly enhance your interaction with the Runes marketplace. Here are some common use cases:
- Automated Trading Bots: Developers can use the API to feed real-time listing data into trading algorithms, enabling automated buying and selling based on predefined criteria like price thresholds.
- Portfolio Dashboards: Build a personalized dashboard that tracks the current listings and market value of your favorite Runes collections.
- Market Analysis Tools: Researchers can aggregate data from multiple API calls to analyze market trends, calculate average sale prices, and identify valuable assets.
To get started, you simply need to construct a HTTP GET request with your desired parameters. Most programming languages have built-in libraries or popular packages (like requests in Python or axios in JavaScript) to handle this task efficiently.
Frequently Asked Questions
What is the primary use of the Runes API?
The primary use is to programmatically retrieve a list of current marketplace listings for a specific Runes token. It provides detailed information on each listing, including owner address, pricing in multiple denominations, and listing status, which is essential for developers building applications on top of the OKX marketplace.
How do I handle pagination for large datasets?
The API supports pagination through the cursor and limit parameters. The cursor points to a specific position in the sorted list of results, allowing you to retrieve the next batch of records in subsequent API calls. The limit parameter controls how many records are returned in a single response, with a maximum of 100.
What does the 'unavailable' status mean in the response?
An unavailable status with a value of 1 indicates that the underlying UTXO contains multiple Atomicals assets. A value of 2 means it contains multiple protocol assets. This is important information as it can affect the fungibility and transferability of the asset.
Can I sort the results by the most recently listed items?
Yes, you can use the sortBy parameter with the value listedTimeDesc to sort the results so that the most recently listed items appear first. Conversely, listedTimeAsc will show the oldest listings first.
Is the USD price provided by the API a real-time value?
The usdPrice field provides the total and unit price converted to US Dollars based on prevailing market rates. While the API aims for accuracy, the precise timing of the rate used should be considered for highly time-sensitive applications.
Do I need an API key to access this endpoint?
The documentation provided does not specify authentication requirements. It is crucial to refer to the official OKX Web3 API documentation for the most current information on authentication, rate limits, and access credentials. 👉 Get advanced methods for API integration