For developers and analysts navigating the Web3 ecosystem, accessing accurate and comprehensive on-chain data is fundamental. This includes everything from a token's basic contract details to its broader social media footprint and market metrics.
This guide provides a clear, structured overview of how to programmatically retrieve this vital project information, a common requirement for building dashboards, portfolio trackers, and research tools.
Understanding Token Details and Metadata
When querying for token information, you can expect to receive a wide array of data points that paint a complete picture of a digital asset. This metadata is crucial for both technical integration and user-facing applications.
Key details typically include:
- Basic Identification: The token's name, symbol, contract address, and decimal precision.
- Project Ecosystem: Official website links and various social media channels like Twitter, GitHub, and Reddit.
- Supply Data: Information on the token's total and maximum supply.
- Market Data: Key metrics such as 24-hour trading volume and overall market capitalization.
This data is aggregated from multiple sources, including direct blockchain queries and integrated market data providers, to ensure a holistic view.
Supported Token Types
A robust API for querying token information should support a wide spectrum of digital assets beyond standard fungible tokens.
Mainnet Coins and Standard Tokens
This covers the foundational assets of any blockchain, such as BTC on Bitcoin or ETH on Ethereum, as well as standard token contracts like ERC-20 on Ethereum or BEP-20 on BNB Chain.
Bitcoin-Based Inscription Tokens
The method also extends to various inscription standards emerging on the Bitcoin network:
- BRC-20: A fungible token standard on Bitcoin.
- Runes: A protocol for creating fungible tokens on Bitcoin.
- SRC-20 & ARC-20: Other experimental token standards utilizing Bitcoin's UTXO model.
- Fractal Bitcoin (FBTC) BRC-20: Tokens on the Fractal Bitcoin layer.
This broad support ensures developers can fetch consistent information across a fragmented landscape of digital assets. For projects requiring deep market analysis, accessing real-time market data endpoints is often the next logical step.
API Request Structure
To retrieve this information, you interact with a specific API endpoint using a GET request.
API EndpointGET https://web3.okx.com/api/v5/wallet/token/token-detail
Core Request Parameters
Two primary parameters are needed to make a successful call:
| Parameter | Type | Required | Description |
|---|---|---|---|
chainIndex | String | Yes | The unique identifier for the blockchain network (e.g., eth, btc). |
tokenAddress | String | No | The token contract address. Rules for this parameter vary: • Use an empty string "" to query the mainnet coin (e.g., ETH). • Use a specific contract address to query a token (e.g., an ERC-20). • For inscription tokens, use a formatted string (e.g., btc-brc20-ordi). |
Interpreting the API Response
A successful API call returns a JSON object packed with information. Understanding these response parameters is key to utilizing the data effectively.
Project and Social Information
logoUrl: A link to the project's official logo image.officialWebsite: The URL of the project's main website.socialUrls: An object containing arrays of URLs for various social platforms (e.g.,twitter,github,reddit). These fields are only returned if data is available.
Token Identification and Chain Data
decimals: The token's decimal precision.tokenAddress: The contract address. This will be an empty string for mainnet coins.chainIndex&chainName: The unique chain identifier and its common name.symbol&name: The ticker symbol and full name of the token.
Supply and Market Metrics
totalSupply&maxSupply: The total and maximum number of tokens in existence.volume24h: The total trading volume in USD over the last 24 hours.marketCap: The total market capitalization of the token in USD.
Note: Supply and market data are often aggregated from multiple sources and may not be available for every token. The numerical precision for these fields is typically up to 15 decimal places.
Frequently Asked Questions
What is the main purpose of this API endpoint?
This endpoint is designed to provide a comprehensive overview of a cryptocurrency or token project. It returns essential technical data like the contract address and decimals, alongside ecosystem information such as social media links and official websites, plus key market metrics.
How do I query the main native coin of a chain (like BTC or ETH)?
To query a chain's native coin, you still must provide the chainIndex parameter (e.g., btc for Bitcoin). For the tokenAddress parameter, you simply pass an empty string: "".
The API didn't return social links for a token. What does this mean?
The social URLs field is optional and is only populated if the data is available and has been indexed. If a field like twitter is missing from the response, it means that information was not found for that specific token.
What is the difference between totalSupply and maxSupply?TotalSupply represents the number of tokens that currently exist and are in circulation. MaxSupply refers to the hard-cap maximum number of tokens that can ever be created. Not all tokens have a defined max supply.
Can this API be used for real-time price data?
While this endpoint returns 24h volume and market cap, which are derived from price, it is not primarily a price-feed API. Its strength lies in providing static project metadata and aggregated market statistics. For dedicated, high-frequency price data, you should explore more specialized market data endpoints.
Why is the market data for some new tokens missing?
Market data like volume24h and marketCap relies on the token being listed on and traded across supported exchanges and liquidity pools. Very new or illiquid tokens may not have this data available immediately. The static project data (website, socials, etc.) should still be returned if available.