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.
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; mandatory for collection-based requests, including metadata refresh requests | No |
accountAddress | The Ethereum address of a wallet holding NFTs; mandatory for owner-based requests | 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 |
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.
- SDK
- API
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,
});
}
Using Immutable's API you can get a specific metadata for a given collection with the following GetMetadata API call; which will produce a result in the below format.
GET /chains/{chain_name}/collections/{contract_address}/metadata/{metadata_id}
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.
- SDK
- API
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,
});
}
Using Immutable's API you can get a list of metadata for a specific collection with the following ListMetadata API call; which will produce a result in the below format.
GET /chains/{chain_name}/collections/{contract_address}/metadata
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="
}
}
List stack bundles and market data
Given a particular metadata stack, get market listings, last trade prices and the number of assets in the stack.
Request parameters
Parameter | Description | Required |
---|---|---|
chainName | String representing the name of the chain. A list of available chains can be found here | Yes |
stackId | Stack_id for metadata to filter by Stack_id for metadata to filter by | Yes |
- SDK
- API
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';
export async function listStacks(
chainName: string,
stackId: string[],
): Promise<blockchainData.Types.StackBundle[]> {
return await client.listStacks({
chainName,
stackId,
});
}
GET /chains/{chain_name}/stacks/{stack_id}
Example response
[
{
"stack": {
"stack_id": "8d268dcf-caa3-4f85-9d09-6ac2a48a6fde",
"chain": {
"id": "eip155:13372",
"name": "imtbl-zkevm-testnet"
},
"contract_address": "string",
"contract_type": "ERC721",
"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": [
{
"display_type": "number",
"trait_type": "Aqua Power",
"value": "Happy"
}
]
},
"stack_count": 1,
"market": {
"floor_listing": {
"listing_id": "018792C9-4AD7-8EC4-4038-9E05C598534A",
"price_details": {
"token": {
"type": "NATIVE",
"symbol": "IMX"
},
"amount": "9750000000000000000",
"fee_inclusive_amount": "9750000000000000000",
"fees": [
{
"type": "TAKER_ECOSYSTEM",
"recipient_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92233",
"amount": "1000000000000000000"
}
],
"converted_prices": {
"ETH": "0.0058079775",
"USD": "15.89"
}
},
"token_id": "1",
"contract_address": "0xe9b00a87700f660e46b6f5deaa1232836bcc07d3",
"creator": "0xe9b00a87700f660e46b6f5deaa1232836bcc07d3",
"amount": "1"
},
"last_trade": {
"trade_id": "4e28df8d-f65c-4c11-ba04-6a9dd47b179b",
"contract_address": "0xe9b00a87700f660e46b6f5deaa1232836bcc07d3",
"token_id": "1",
"price_details": [
{
"token": {
"type": "NATIVE",
"symbol": "IMX"
},
"amount": "9750000000000000000",
"fee_inclusive_amount": "9750000000000000000",
"fees": [
{
"type": "TAKER_ECOSYSTEM",
"recipient_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92233",
"amount": "1000000000000000000"
}
],
"converted_prices": {
"ETH": "0.0058079775",
"USD": "15.89"
}
}
],
"amount": "1",
"created_at": "2022-08-16T17:43:26.991388Z"
}
},
"listings": [
{
"listing_id": "018792C9-4AD7-8EC4-4038-9E05C598534A",
"price_details": {
"token": {
"type": "NATIVE",
"symbol": "IMX"
},
"amount": "9750000000000000000",
"fee_inclusive_amount": "9750000000000000000",
"fees": [
{
"type": "TAKER_ECOSYSTEM",
"recipient_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92233",
"amount": "1000000000000000000"
}
],
"converted_prices": {
"ETH": "0.0058079775",
"USD": "15.89"
}
},
"token_id": "1",
"contract_address": "0xe9b00a87700f660e46b6f5deaa1232836bcc07d3",
"creator": "0xe9b00a87700f660e46b6f5deaa1232836bcc07d3",
"amount": "1"
}
]
}
]