Get NFT data

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

Sections

• List all NFTs
• List NFTs from a particular collection
• List NFTs owned by a particular wallet
• Get the details of a single NFT​
• List NFT owners​

---

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
Pagination parameters	Parameters such as page_size and page_cursor that allow you to control the size and order of the data retrieved	No

SDK

const chainName = CHAIN_NAME;
const response = await client.listAllNFTs({ chainName });

API

📚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",
      "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

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
Pagination parameters	Parameters such as page_size and page_cursor that allow you to control the size and order of the data retrieved	No

SDK

const chainName = CHAIN_NAME;
const contractAddress = CONTRACT_ADDRESS;
const tokenId = ['1', '2'];
const response = await client.listNFTs({chainName, contractAddress, tokenId });

API

📚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",
      "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

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
Pagination parameters	Parameters such as page_size and page_cursor that allow you to control the size and order of the data retrieved	No

SDK

const chainName = CHAIN_NAME;
const accountAddress = ACCOUNT_ADDRESS;
const contractAddress = CONTRACT_ADDRESS;
const response = await client.listNFTsByAccountAddress({ chainName, accountAddress, contractAddress });

API

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

SDK

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

API

📚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": "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.

SDK

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

API

📚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",
      "updated_at": "2022-08-16T17:43:26.991388Z"
    }
  ],
  "page": {
    "previous_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0=",
    "next_cursor": "ewogICJ0eXBlIjogInByZXYiLAogICJpdGVtIjogewogICAgImlkIjogNjI3NTEzMCwKICAgICJjcmVhdGVkX2F0IjogIjIwMjItMDktMTNUMTc6MDQ6MTIuMDI0MTI2WiIKICB9Cn0="
  }
}