Skip to main content

Get NFT data

Immutable's Blockchain Data APIs allow developers to retrieve data about non-fungible (ERC721) and semi-fungible (ERC1155) NFTs 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
fromUpdatedAtDatetime to use as the oldest updated timestampNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
listAllNFTs.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listAllNFTs(): Promise<blockchainData.Types.ListNFTsResult> {
return await client.listAllNFTs({
chainName: 'imtbl-zkevm-testnet',
});
}

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": "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"
}
],
"total_supply": "1"
}
],
"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
fromUpdatedAtDatetime to use as the oldest updated timestampNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
listNFTsByCollection.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listNFTsByCollection(
contractAddress: string,
tokenId: string[],
): Promise<blockchainData.Types.ListNFTsResult> {
return await client.listNFTs({
chainName: 'imtbl-zkevm-testnet',
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": "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"
}
],
"total_supply": "1"
}
],
"page": {
"previous_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0=",
"next_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0="
}
}

List NFTs owned by a particular account address

This request returns a paginated list of all the NFTs that belong to a particular account address (owner).

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
fromUpdatedAtDatetime to use as the oldest updated timestampNo
tokenIdThe token ID string you want to returnNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
listNFTsByAccountAddress.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listNFTsByAccountAddress(
chainName: string,
contractAddress: string,
accountAddress: string,
): Promise<blockchainData.Types.ListNFTsResult> {
return await client.listNFTsByAccountAddress({
chainName,
contractAddress,
accountAddress,
});
};

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 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.

import { blockchainData } from "@imtbl/sdk";
import { client } from "../lib";

export async function getNFT(chainName: string, contractAddress: string, tokenId: string): Promise<blockchainData.Types.GetNFTResult> {
return await client.getNFT({
chainName: chainName,
contractAddress: contractAddress,
tokenId: 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": "ERC1155",
"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"
}
],
"total_supply": "100"
}
}

List all NFT owners

This request allows you to get the details of all owners.

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found here.Yes
fromUpdatedAtDatetime to use as the oldest updated timestampNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
listAllNFTOwners.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listAllNFTOwners(): Promise<blockchainData.Types.ListNFTOwnersResult> {
return await client.listAllNFTOwners({
chainName: 'imtbl-zkevm-testnet',
});
}

Example response

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

List NFT owners of particular token ID

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.

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found here.Yes
contractAddressThe address of the contractYes
tokenIdThe address of the contractYes
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
listNFTOwnersByTokenId.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listNFTOwnersByTokenId(
contractAddress: string,
tokenId: string,
): Promise<blockchainData.Types.ListNFTOwnersResult> {
return await client.listNFTOwners({
chainName: 'imtbl-zkevm-testnet',
contractAddress,
tokenId,
});
}

Example response

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

List NFT owners from a particular collection

This request returns a paginated list of all the NFT owners 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 address of the contractYes
accountAddressThe public address of a wallet holding NFTsNo
fromUpdatedAtDatetime to use as the oldest updated timestampNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo
listNFTOwnersByContractAddress.tsView on GitHub
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';

export async function listNFTOwnersByContractAddress(
contractAddress: string,
): Promise<blockchainData.Types.ListNFTOwnersResult> {
return await client.listNFTOwnersByContractAddress({
chainName: 'imtbl-zkevm-testnet',
contractAddress,
});
}

Example response

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