Skip to main content

Get NFT data

Immutable's Blockchain Data APIs allow developers to retrieve data about non-fungible (ERC721) tokens on Immutable-supported chains.

Immutable Rollups comparisonImmutable Rollups comparison

List all NFTs

This request returns a paginated list of all the NFTs that belong to a particular chain.

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found here.Yes
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
const chainName = CHAIN_NAME;
const response = await client.listAllNFTs({ chainName });

Note: The NFT owner is not included in the response of this query. Use listNFTOwners for this feature.

Example response

{
"result": [
{
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"token_id": "1",
"contract_address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
"indexed_at": "2022-08-16T17:43:26.991388Z",
"updated_at": "2022-08-16T17:43:26.991388Z",
"metadata_synced_at": "2022-08-16T17:43:26.991388Z",
"metadata_id": "ae83bc80-4dd5-11ee-be56-0242ac120002",
"name": "Sword",
"description": "2022-08-16T17:43:26.991388Z",
"image": "https://some-url",
"external_link": "https://some-url",
"animation_url": "https://some-url",
"youtube_url": "https://some-url",
"attributes": [
{
"trait_type": "Aqua Power",
"value": "Happy"
}
]
}
],
"page": {
"previous_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0=",
"next_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0="
}
}

List NFTs from a particular collection

This request returns a paginated list of all the NFTs that belong to a particular collection.

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found here.Yes
contractAddressThe contract address of ERC721 contract you want to filter byYes
tokenIdAn array of token IDs strings to filter the returned list byNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
const chainName = CHAIN_NAME;
const contractAddress = CONTRACT_ADDRESS;
const tokenId = ['1', '2'];
const response = await client.listNFTs({chainName, contractAddress, tokenId });

Note: The NFT owner is not included in the response of this query. Use listNFTOwners for this feature.

Example response

{
"result": [
{
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"token_id": "1",
"contract_address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
"indexed_at": "2022-08-16T17:43:26.991388Z",
"updated_at": "2022-08-16T17:43:26.991388Z",
"metadata_synced_at": "2022-08-16T17:43:26.991388Z",
"metadata_id": "ae83bc80-4dd5-11ee-be56-0242ac120002",
"name": "Sword",
"description": "2022-08-16T17:43:26.991388Z",
"image": "https://some-url",
"external_link": "https://some-url",
"animation_url": "https://some-url",
"youtube_url": "https://some-url",
"attributes": [
{
"trait_type": "Aqua Power",
"value": "Happy"
}
]
}
],
"page": {
"previous_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0=",
"next_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0="
}
}

List NFTs owned by a particular wallet

This request returns a paginated list of all the NFTs that belong to a particular wallet address (owner), including details like the collection it belongs to, when it was minted, and its metadata.

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found here.Yes
accountAddressThe public address of a wallet holding NFTsYes
contractAddressThe contract address of ERC721 contract you want to filter byNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
const chainName = CHAIN_NAME;
const accountAddress = ACCOUNT_ADDRESS;
const contractAddress = CONTRACT_ADDRESS;
const response = await client.listNFTsByAccountAddress({ chainName, accountAddress, contractAddress });

Note: The NFT owner is not included in the response of this query. Use listNFTOwners for this feature.

Example response

{
"result": [
{
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"token_id": "1",
"contract_address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
"contract_type": "erc721",
"indexed_at": "2022-08-16T17:43:26.991388Z",
"updated_at": "2022-08-16T17:43:26.991388Z",
"metadata_synced_at": "2022-08-16T17:43:26.991388Z",
"metadata_id": "ae83bc80-4dd5-11ee-be56-0242ac120002",
"name": "Sword",
"description": "This is a super awesome sword",
"image": "https://some-url",
"external_link": "https://some-url",
"animation_url": "https://some-url",
"youtube_url": "https://some-url",
"attributes": [
{
"trait_type": "Aqua Power",
"value": "Happy"
}
],
"balance": "11"
}
],
"page": {
"previous_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0=",
"next_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0="
}
}

Note: The NFT owner is not included in the response of this query. Use listNFTOwners for this feature.

Get the details of a single NFT​

This request allows you to get details of a specific NFT, including details like the collection it belongs to, when it was minted, and its metadata.

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found here.Yes
contractAddressThe contract address of ERC721 contract you want to filter byYes
tokenIdThe token ID string you want to returnYes
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
💡Where is NFT metadata hosted?

When an asset is minted, its metadata is cached by Immutable's blockchain data indexer, making it accessible via the the Blockchain Data APIs.

When an NFT's metadata is updated, requesting a "metadata refresh" updates the cached information to ensure that changes are available via the API.

const chainName = CHAIN_NAME;
const contractAddress = CONTRACT_ADDRESS;
const tokenId = '1';
const response = await client.getNFT({ chainName, contractAddress, tokenId });

Note: The NFT owner is not included in the response of this query. Use listNFTOwners for this feature.

Example response

{
"result": {
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"token_id": "1",
"contract_address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
"contract_type": "erc721",
"indexed_at": "2022-08-16T17:43:26.991388Z",
"updated_at": "2022-08-16T17:43:26.991388Z",
"metadata_synced_at": "2022-08-16T17:43:26.991388Z",
"metadata_id": "ae83bc80-4dd5-11ee-be56-0242ac120002",
"name": "Sword",
"description": "This is a super awesome sword",
"image": "https://some-url",
"external_link": "https://some-url",
"animation_url": "https://some-url",
"youtube_url": "https://some-url",
"attributes": [
{
"trait_type": "Aqua Power",
"value": "Happy"
}
]
}
}

List NFT owners​

This request allows you to get the details of all owners that have custody of a single NFT. For ERC721 NFTs, only a single owner will be returned. If multi-owner token standards are added to the Data APIs, this API may return a list in future.

const chainName = CHAIN_NAME;
const contractAddress = CONTRACT_ADDRESS;
const tokenId = TOKEN_ID;
const response = await client.listNFTOwners({chainName, contractAddress, tokenId});

Example response

{
"result": [
{
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"contract_address": "0x5a019874f4fae314b0eaa4606be746366e661306",
"token_id": "1",
"account_address": "0x5a019874f4fae314b0eaa4606be746366e661306",
"quantity": "1",
"updated_at": "2022-08-16T17:43:26.991388Z"
}
],
"page": {
"previous_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0=",
"next_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0="
}
}

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us