This comprehensive guide explains how to use the OKX Runes API to retrieve listing information for Runes tokens on the OKX marketplace. The API supports querying specific collection details using runesId.
API Overview
The get-runes-order-list endpoint allows developers to:
- Retrieve active listings for Runes tokens
- Filter by specific collections using
runesId - Access comprehensive order details including pricing and status information
API Endpoint
Request Method: GET
Endpoint URL: https://web3.okx.com/api/v5/mktplace/nft/runes/get-runes-order-list
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| runesId | String | Yes | Unique identifier for the Runes token |
| cursor | String | No | Pagination cursor (max 1,000 records) |
| limit | Integer | No | Results per page (default: 10, max: 100) |
| sortBy | String | No | Sorting criteria (see options below) |
Sorting Options
unitPriceAsc: Ascending unit priceunitPriceDesc: Descending unit pricetotalPriceAsc: Ascending total pricetotalPriceDesc: Descending total pricelistedTimeAsc: Oldest listings firstlistedTimeDesc: Newest listings first
Response Parameters
The API returns detailed information about each listing:
| Parameter | Type | Description |
|---|---|---|
| assetId | Integer | Database primary key |
| tickerType | String | Token type (4 for Runes) |
| ticker | Integer | Token name |
| tickerId | String | Token identifier |
| ownerAddress | String | Owner's wallet address |
| amount | String | XRC20 amount in UTXO |
| chain | Integer | Blockchain identifier |
| inscriptionNum | String | Inscription number |
| utxoTxHash | String | Transaction hash |
| utxoVout | Integer | UTXO vout value |
| utxoValue | String | UTXO value |
| txHash | String | Transaction hash |
| name | String | Token name |
| tickerIcon | String | Token icon URL |
| status | Integer | Listing status (0-2) |
| listTime | Long | Timestamp of listing |
| orderId | Long | Order identifier |
| confirmations | Long | Block height info |
| currency | String | Price currency |
| currencyUrl | String | Currency logo URL |
| satPrice | BigDecimal | Price in satoshis |
| price | BigDecimal | Price in BTC |
| usdPrice | BigDecimal | Price in USD |
| symbol | String | Currency symbol |
Implementation Guide
👉 For complete API documentation and integration examples
- Authentication: Ensure you have proper API keys
- Rate Limits: Be aware of request limitations
- Error Handling: Implement robust error handling
- Data Caching: Consider caching frequent requests
FAQ Section
What is the maximum number of records I can retrieve?
The API supports retrieving up to 1,000 records using cursor pagination.
How often is the listing data updated?
Listing data is updated in real-time as new orders are created or modified.
Can I filter listings by price range?
While the current API doesn't support price range filters, you can implement client-side filtering after retrieval.
What status codes indicate a successful request?
HTTP 200 indicates success, while 4xx/5xx codes indicate various error conditions.
👉 For advanced filtering options and premium API features
Best Practices
- Always include error handling for network issues
- Cache frequently accessed data to reduce API calls
- Implement exponential backoff for rate-limited requests
- Monitor API response times for performance optimization
Conclusion
This API provides comprehensive access to Runes token listings on OKX's marketplace. By following this guide and implementing the suggested best practices, developers can effectively integrate this functionality into their applications.
For additional support, visit our developer portal or join the community forums.