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.

Sections

List all NFTs
List NFTs from a particular collection
List NFTs owned by a particular account address
Get the details of a single NFT
List all NFT owners
List NFT owners of particular token ID
List NFT owners from a particular collection

List all NFTs

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

Request parameters

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`fromUpdatedAt`	Datetime to use as the oldest updated timestamp	No
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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',
  });
}

📚API reference

ListNFTs

GET {baseURL}/v1/chains/{chain_name}/nfts

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

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`contractAddress`	The contract address of ERC721 contract you want to filter by	Yes
`tokenId`	An array of token IDs strings to filter the returned list by	No
`fromUpdatedAt`	Datetime to use as the oldest updated timestamp	No
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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,
  });
}

📚API reference

ListNFTs

GET {baseURL}/v1/chains/{chain_name}/collections/{contract_address}/nfts

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

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`accountAddress`	The public address of a wallet holding NFTs	Yes
`contractAddress`	The contract address of ERC721 contract you want to filter by	No
`fromUpdatedAt`	Datetime to use as the oldest updated timestamp	No
`tokenId`	The token ID string you want to return	No
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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.ListNFTsByOwnerResult> {
  return await client.listNFTsByAccountAddress({
    chainName,
    contractAddress,
    accountAddress,
  });
}

📚API reference

ListNFTsByAccountAddress

GET {baseURL}/v1/chains/{chainName}/accounts/{address}/nfts

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

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`contractAddress`	The contract address of ERC721 contract you want to filter by	Yes
`tokenId`	The token ID you want to return	Yes
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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

getNFT.tsView on GitHub
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,
  });
}

📚API reference

GetNFT

GET {baseURL}/v1/chains/{chainName}/collections/{contractAddress}/nfts/{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

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`fromUpdatedAt`	Datetime to use as the oldest updated timestamp	No
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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',
  });
}

📚API reference

ListNFTOwners

GET {baseURL}/v1/chains/{chainName}/nft-owners

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

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`contractAddress`	The address of the contract	Yes
`tokenId`	The address of the contract	Yes
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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,
  });
}

📚API reference

ListNFTOwners

GET {baseURL}/v1/chains/{chainName}/collections/{contractAddress}/nfts/{tokenId}/owners

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

Parameter	Description	Required
`chainName`	String representing the name of the chain. A list of available chains can be found here.	Yes
`contractAddress`	The address of the contract	Yes
`accountAddress`	The public address of a wallet holding NFTs	No
`fromUpdatedAt`	Datetime to use as the oldest updated timestamp	No
Pagination parameters	Parameters such as `page_size` and `page_cursor` that allow you to control the size and order of the data retrieved	No

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,
  });
}

📚API reference

ListNFTOwners

GET {baseURL}/v1/chains/{chainName}/collections/{contractAddress}/owners

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="
  }
}

Get NFT data

List all NFTs​

Request parameters​

Example response​

List NFTs from a particular collection​

Request parameters​

Example response​

List NFTs owned by a particular account address​

Request parameters​

Example response​

Get the details of a single NFT​

Request parameters​

Example response​

List all NFT owners​

Request parameters​

Example response​

List NFT owners of particular token ID​

Request parameters​

Example response​

List NFT owners from a particular collection​

Request parameters​

Example response​

List all NFTs

Request parameters

Example response

List NFTs from a particular collection

Request parameters

Example response

List NFTs owned by a particular account address

Request parameters

Example response

Get the details of a single NFT

Request parameters

Example response

List all NFT owners

Request parameters

Example response

List NFT owners of particular token ID

Request parameters

Example response

List NFT owners from a particular collection

Request parameters

Example response