Retrieve Detailed Runes Collection Data via API

·

Introduction

The Runes API provides a streamlined interface for accessing comprehensive information about specific Runes token collections on the blockchain. By querying this API, developers and market analysts can retrieve essential on-chain and market data, including holder counts, trading activity, and pricing metrics. This data is crucial for building analytical dashboards, tracking collection performance, and integrating real-time NFT marketplace statistics into applications.

This guide details the technical specifications for making a successful request to the runes/detail endpoint and correctly interpreting the wealth of information returned in the response.

API Request Specifications

To fetch data for a Runes collection, you must make a GET request to the designated endpoint with the required parameters.

Endpoint and Method

The request is sent using the GET HTTP method to the following address:

https://web3.okx.com/api/v5/mktplace/nft/runes/detail

Required Query Parameters

A single parameter is required to execute a query. It can be used to request data for a single Rune or for multiple Runes in a single batch call.

ParameterTypeRequiredDescription
runesIdStringYesThe unique identifier for the Rune. Supports batch queries by using a comma (,) to separate multiple IDs. Example: 840000:3,840000:28

Understanding the API Response

A successful API call returns a JSON object containing a detailed set of fields that describe the specified Runes collection(s). The data is divided into core token properties, minting details, and key market statistics.

Response Parameters Explained

The response includes the following parameters, providing a holistic view of each collection.

Core Identification & Properties

Minting Details

Market Data & Statistics

For developers looking to integrate this data into trading tools or analytics platforms, a reliable data source is essential. You can explore more strategies for leveraging real-time market APIs in your projects.

Practical Implementation: Code Examples

To help you get started, here are examples of how a typical request is structured and what a response might look like.

Example Request

This example shows a cURL command to fetch data for two Runes with IDs 840000:3 and 840000:28.

curl -X GET "https://web3.okx.com/api/v5/mktplace/nft/runes/detail?runesId=840000:3,840000:28"

Example Response

A successful request will return a response with a structure similar to the following JSON object.

{
  "code": "0",
  "data": [
    {
      "runesId": "840000:3",
      "name": "EXAMPLE.RUNE",
      "spacename": "EXAMPLE•RUNE",
      "maxMintNumber": "10000",
      "mintedNumber": "7500",
      "limitPerMint": "100",
      "deployedTime": 1711234567890,
      "startBlock": "840000",
      "endBlock": "842000",
      "symbol": "EXR",
      "divisibility": 0,
      "collectionUrl": "https://www.okx.com/join/BLOCKSTARweb3/marketplace/runes/840000:3",
      "totalVolume": "2.5",
      "usdTotalVolume": "150000.00",
      "marketCap": "120.75",
      "usdMarketCap": "7250000.00",
      "floorprice": "250000",
      "usdFloorPrice": "150.00",
      "holders": 1250,
      "salesCount": 5800
    }
  ],
  "msg": ""
}

Frequently Asked Questions

What is a Runes ID and how do I find it?
A Runes ID is a unique on-chain identifier typically composed of a block height and a unique index within that block (e.g., 840000:3). You can often find this ID by browsing Runes collections on marketplace explorers or dedicated tracking websites.

Can I get data for all Runes collections at once?
No, this specific endpoint requires you to specify one or more runesId parameters. To get a list of all collections, you would need to use a different API endpoint designed for listing assets before drilling down into the details provided here.

What is the difference between totalVolume and marketCap?
totalVolume represents the sum of all historical trades for the collection, indicating overall trading activity. marketCap is a calculated value (typically floor price multiplied by total supply) that estimates the total value of all tokens in the collection at the current market price.

How frequently is the market data (like floor price) updated?
The market data within the API response is updated in near real-time, reflecting the latest changes and transactions occurring on the marketplace and blockchain. This ensures your application displays the most current information available.

Why are both BTC and USD values provided?
Providing values in both Bitcoin (BTC) and US Dollars (USD) caters to different user preferences. BTC values are native to the blockchain environment, while USD values offer a stable fiat currency reference for easier valuation and comparison for a global audience. To view real-time tools that utilize this dual-pricing data, you can investigate various developer resources.

What should I do if I get an error response?
First, verify that the runesId parameter is formatted correctly and that you are using a valid ID. Common errors are usually related to incorrect parameter formatting or invalid IDs. Ensure there are no extra spaces in your comma-separated list of IDs.