Skip to main content

Get & update metadata

Immutable's Blockchain Data APIs allows developers and 3rd parties to access all collection's off-chain metadata in a centralised location. Metadata is essential in defining the context, characteristics, and aesthetics of NFTs.

Get & update metadata dataGet & update metadata data

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain. A list of available chains can be found hereYes
contractAddressThe contract address of ERC721 contract you want to filter by; mandatory for collection-based requests, including metadata refresh requestsNo
accountAddressThe Ethereum address of a wallet holding NFTs; mandatory for owner-based requestsNo
Pagination parametersParameters such as page_size and page_cursor that allow you to control the size and order of the data retrievedNo

Get a single metadata

This request allows you to get details of a specific metadata object referenced by a metadata_id. A metadata_id corresponds to the metadata of all stacked NFTs that shares the same metadata attributes.

get-metadata.tsView on GitHub
import { blockchainData } from "@imtbl/sdk";
import { client } from "../lib";

export async function getMetadata(
chainName: string,
contractAddress: string,
metadataId: string
): Promise<blockchainData.Types.GetMetadataResult> {
return await client.getMetadata({
chainName,
contractAddress,
metadataId,
});
}

Example response

{
"result": {
"id": "4e28df8d-f65c-4c11-ba04-6a9dd47b179b",
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"contract_address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
"created_at": "2022-08-16T17:43:26.991388Z",
"updated_at": "2022-08-16T17:43:26.991388Z",
"name": "Sword",
"description": "2022-08-16T17:43:26.991388Z",
"image": "https://some-url",
"external_url": "https://some-url",
"animation_url": "https://some-url",
"youtube_url": "https://some-url",
"attributes": [
{
"trait_type": "Aqua Power",
"value": "Happy"
}
]
}
}

List metadata of a specific collection

This request returns a list of metadata of a specific collection. A metadata_id can correlate to a single NFT or a stack of NFTs that share the same metadata attributes. Results will be sorted by updated_at, with the most recent entries first.

list-metadata.tsView on GitHub
import { blockchainData } from "@imtbl/sdk";
import { client } from "../lib";

export async function listMetadata(
chainName: string,
contractAddress: string
): Promise<blockchainData.Types.ListMetadataResult> {
return await client.listNFTMetadataByContractAddress({
chainName,
contractAddress,
});
}

Example response

{
"result": [
{
"id": "4e28df8d-f65c-4c11-ba04-6a9dd47b179b",
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"contract_address": "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e",
"created_at": "2022-08-16T17:43:26.991388Z",
"updated_at": "2022-08-16T17:43:26.991388Z",
"name": "Sword",
"description": "2022-08-16T17:43:26.991388Z",
"image": "https://some-url",
"external_url": "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="
}
}