In the rapidly evolving world of Web3 and digital collectibles, accessing precise and detailed information about Non-Fungible Tokens (NFTs) is crucial for developers, collectors, and platforms alike. The NFT Asset Detail API provides a standardized, powerful method to retrieve comprehensive data about a specific NFT, including its metadata, visual assets, attributes, and the collection it belongs to. This guide will walk you through the functionality, parameters, and practical application of this essential API endpoint.
Understanding the API Endpoint
This interface is designed to fetch intricate details about an NFT asset. The returned data encompasses the token's core information, collection details, smart contract data, and its unique attributes. This is fundamental for building applications that display NFTs, verify authenticity, or analyze digital asset properties.
API Request Structure
To successfully call this API, you must use a GET request to the following address:
https://web3.okx.com/api/v5/mktplace/nft/asset/detail
Required Parameters for the Request
Three specific parameters are mandatory to identify the exact NFT you wish to query. All three must be provided for a successful request.
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | String | Yes | The name of the blockchain network on which the NFT resides. You must use a chain from the list of supported networks. |
contractAddress | String | Yes | The unique address of the smart contract that issued the NFT. This must be a valid and existing contract address. |
tokenId | String | Yes | The unique identifier (ID) of the specific NFT within the given contract. |
Understanding the Response Data
A successful API call returns a rich set of data organized into several key fields. This structure provides a holistic view of the digital asset.
| Parameter | Type | Description |
|---|---|---|
name | String | The human-readable name of the NFT. |
tokenId | String | The unique token ID that identifies this NFT within its contract. |
tokenUri | String | The URI (Uniform Resource Identifier) pointing to the NFT's full metadata JSON file. |
image | String | The direct URL to the main image file for the NFT. |
imagePreviewUrl | String | A URL for a smaller, quickly loadable preview version of the NFT's image. |
imageThumbnailUrl | String | A URL for a thumbnail-sized version of the NFT's image. |
animationUrl | String | If the NFT is a video, audio, or interactive file, this is the URL to that resource. |
attributes | Object | An object containing the NFT's specific traits or properties (e.g., rarity, color, feature). This follows a standardized attribute model. |
assetContracts | Object | An object containing detailed information about the smart contract that created the NFT, based on a contract information model. |
collection | Object | An object containing high-level information about the entire collection this NFT is a part of, following a collection model. |
Practical Applications and Use Cases
This API is incredibly versatile and serves as a backbone for numerous Web3 functionalities. Developers can use it to power NFT marketplaces, allowing users to view detailed asset pages with images, descriptions, and traits. Wallet applications can integrate it to display the NFTs a user owns with rich visuals and metadata. Furthermore, analytics platforms can leverage this data to track rarity scores, attribute distribution, and collection statistics across the entire market. For projects requiring deep integration with real-time NFT data, this API is an indispensable tool. 👉 Explore more strategies for API integration
Frequently Asked Questions
What is the primary purpose of the NFT Asset Detail API?
This API is designed to provide a complete dataset for a single NFT. It returns everything from its basic identification (name, tokenId) and media files (image, animationUrl) to its contextual information within a collection and its unique on-chain attributes.
Why are all three parameters (chain, contractAddress, tokenId) mandatory?
These three pieces of information form a unique triple-key that pinpoints one specific NFT across the entire multichain ecosystem. The chain specifies the blockchain, the contractAddress identifies the originating project, and the tokenId singles out the individual asset, ensuring there is no ambiguity in the request.
What kind of information can I find in the attributes object?
The attributes object contains an array of the NFT's specific traits or properties. This often includes details like "Background," "Fur," "Eyes" for a profile picture (PFP) project, along with their corresponding values and sometimes a rarity score. The exact structure is defined by the project that created the NFT.
How can I use the tokenUri field?
The tokenUri contains a pointer (often an IPFS hash or a URL) to a JSON file that holds the NFT's original metadata. You can fetch this data separately to get the complete information that the creator originally assigned to the token, which may include additional details not directly mirrored in the API response.
What is the difference between image, imagePreviewUrl, and imageThumbnailUrl?
These fields provide the same core image at different resolutions. The image is typically the full-size, high-resolution version. The imagePreviewUrl is a medium-sized version optimized for fast loading in galleries or lists. The imageThumbnailUrl is the smallest version, ideal for icons or contexts where space is limited.
Is this API suitable for building a marketplace?
Absolutely. This API provides all the critical on-chain and off-chain data required to display an NFT listing page, including the asset's media, its name, its traits for filtering, and the collection it belongs to for context and verification. It is a fundamental building block for any NFT marketplace or gallery.