This API provides developers with a streamlined interface to retrieve a list of Non-Fungible Tokens (NFTs) associated with a specific smart contract deployed on a particular blockchain network. It is an essential component for building applications that interact with digital collectibles and blockchain-based assets.
API Endpoint and Request Structure
The primary function of this interface is to fetch NFT data from a specified contract address on a supported blockchain. The request is executed using a standard HTTP GET method.
HTTP Request
GET https://web3.okx.com/api/v5/mktplace/nft/asset/listRequired and Optional Parameters
To successfully call this API, you must provide specific parameters that define your query. The following table outlines these parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | String | Yes | The name of the blockchain network (e.g., Ethereum, BNB Smart Chain). |
contractAddress | String | Yes | The valid smart contract address from which to fetch the NFTs. |
cursor | String | No | A pagination cursor for retrieving a specific page of results. |
limit | String | No | The number of items to return per page. The default and maximum value is 300. |
Understanding the API Response
Upon a successful call, the API returns a response containing an array of detailed NFT objects. Each object is a comprehensive data model representing a single NFT asset.
Key Response Data Fields
The response includes a wealth of information for each NFT, which is crucial for applications like marketplaces, galleries, or wallets.
| Parameter | Type | Description |
|---|---|---|
name | String | The name or title of the specific NFT. |
tokenId | String | The unique identifier of the NFT within its contract. |
tokenUri | String | The URI pointing to the NFT's metadata JSON file. |
image | String | The direct URL to the NFT's full-size image asset. |
imagePreviewUrl | String | A URL for a smaller, optimized preview image. |
imageThumbnailUrl | String | A URL for a very small thumbnail image. |
animationUrl | String | A URL for animation or video assets, if applicable. |
attributes | Object | An object detailing the NFT's traits and properties. |
assetContracts | Object | An object containing information about the smart contract. |
collection | Object | An object containing details about the NFT's parent collection. |
For a deeper dive into the structure of the attributes, contract, and collection objects, developers should consult the relevant detailed model documentation. This API is a powerful tool for integrating real-time NFT data directly into your dApp or service. To explore more strategies for implementing Web3 APIs, consider reviewing additional developer resources.
Common Use Cases and Implementation
This API is designed for versatility and can be the backbone for numerous Web3 applications.
Building an NFT Marketplace
Developers can use this endpoint to populate marketplace listings. By calling the API with a specific contract address, you can display all assets within a collection, complete with their images, names, and traits for users to browse and purchase.
Creating Portfolio Trackers
Wallet applications and portfolio dashboards can integrate this API to show users a complete list of the NFTs they own from a particular collection, providing a clear overview of their digital assets.
Powering Analytics Platforms
Data analysts can leverage this API to gather information about NFT collections for analysis. This can include tracking rarity, monitoring distribution, and generating insights about specific projects on various blockchains.
Frequently Asked Questions
What is the primary purpose of this NFT API?
This API is designed to fetch a list of all NFTs contained within a specified smart contract on a given blockchain. It returns detailed metadata for each asset, which is essential for building applications that display or analyze NFT collections.
How does pagination work with this endpoint?
The API supports pagination through the cursor and limit parameters. If a response contains a large number of items, it may return a cursor string. Use this cursor in your subsequent request to retrieve the next page of results.
What chains are supported by this API?
The API supports multiple blockchain networks. The exact list of supported chains is detailed in the official Web3 API documentation, which includes major networks like Ethereum and other Ethereum Virtual Machine (EVM) compatible chains.
Is the contractAddress parameter case-sensitive?
Yes, blockchain addresses are typically case-sensitive. It is crucial to provide the contract address in the correct casing (usually checksummed) as it exists on the blockchain to ensure a successful API response.
Can I filter the results to a specific token ID?
No, this particular endpoint retrieves a list of assets from a collection. To get information for a single, specific token ID, you would need to use a different API endpoint designed for querying individual NFT metadata.
What should I do if I receive an empty response?
An empty array response typically indicates that the provided contract address does not contain any NFT assets, the chain parameter is incorrect, or the address is invalid. Double-check your parameters for accuracy. For advanced troubleshooting methods, you can get advanced methods from the developer support portal.