Skip to main content

Metadata refresh


What is a metadata refresh call?

Upon the initial minting of an NFT, the metadata associated with it is automatically indexed by the Blockchain Data API. However, gaming assets are inherently dynamic, subject to attribute changes driven by player actions such as crafting or in-game performance enhancements. These updates significantly contribute to the evolving in-game experience. Nevertheless, these alterations do not automatically propagate across Immutable's gaming ecosystem, leading to a lack of awareness among marketplaces, aggregators, and other third-party entities interconnected with the platform.

This unawareness has the potential to impact the perceived value of these assets. To address this, the metadata refresh service has been developed, primarily catering to game studios. Its core purpose is to serve as a means for these studios to inform the community of asset evolution, thereby enhancing transparency within the ecosystem. This, in turn, benefits players, as they gain the opportunity to be duly rewarded for any improvements made to their assets should they choose to list them on marketplaces.

What is a metadata_id?

All minted assets are assigned two key identifiers: a token_id and a metadata_id, both of which are accessible through the nft endpoint.

  1. The token_id serves as a unique identifier for each asset within a specific collection. It distinguishes one asset from another within that collection. token_id can be game studio specified if mint() or batchMint() functions are used from Immutable's preset contract.

  2. The metadata_id, on the other hand, uniquely identifies the metadata associated with one or more assets within the same collection. metadata_id are auto generated by Immutable.

Notably, NFTs that share identical metadata characteristics, often referred to as stacked assets, will all be linked to the same metadata_id, a process automatically managed by Immutable's Blockchain Data API.

For instance, consider two cards represented as NFTs, both possessing exactly the same features. Each of these cards would have its own distinct token_id, allowing them to be individually recognized within the collection. However, they would share the same metadata_id since their metadata attributes are identical.

Now, let's say one of these cards undergoes an upgrade through a crafting action. As a result, it would be assigned a new metadata_id, which can be accessed via the nft endpoint. Meanwhile, the other card would retain its original metadata_id. If the upgraded card is the only asset within the collection that possesses these unique metadata attributes, it will receive a new metadata_id. However, if there are other NFTs within the collection that share the same metadata attributes, the upgraded card will be assigned an existing metadata_id associated with these similar NFTs.

The below table demonstrates how metadata_id changes in different metadata update scenarios:

SituationMetadata ChangeMetadata Refresh ByAsset After RefreshMetadata ID
1 asset with unique metadataUpdate metadatatoken_idUnique metadataNew metadata_id
1 asset with unique metadataUpdate metadatatoken_idAsset has metadata equal to a stack of assets assigned with metadata_id=XRefreshed asset assigned metadata_id=X
1 asset with unique metadataUpdate metadatametadata_idUnique metadataNo change to metadata_id
1 asset with unique metadataUpdate metadatametadata_idAsset has metadata equal to a stack of assets assigned with metadata_id=XError generated. Cannot have 2 metadata_ids representing identical stacked assets
100 assets sharing metadataChange 1 asset's metadatatoken_idUnique metadataNew metadata_id
100 assets sharing metadataChange 1 asset's metadatatoken_idAsset has metadata equal to a stack of assets assigned with metadata_id=XRefreshed asset assigned metadata_id=X
100 assets sharing metadataChange 100 assets' metadatametadata_idUnique metadata for stackNo change to metadata_id
100 assets sharing metadataChange 100 assets' metadatametadata_idAssets has metadata equal to a stack of assets assigned with metadata_id=XError generated. Cannot have 2 metadata_ids representing identical stacked assets

Once a metadata_id has been created it will persist even if there are no assets that currently have that metadata_id. If an asset is assigned metadata represented by a legacy metadata_id, it will be assigned the legacy metadata_id.

See the following example to illustrate this point:

  1. An unique asset has the following metadata: Animal=Dragon, Colour=Green, Strength=10 -> assigned metadata_id=A1
  2. This asset has its metadata updated to the following: Animal=Dragon, Colour=Red, Strength=10 -> assigned metadata_id=A2, no assets currently have metadata_id=A1
  3. This asset has its metadata updated back to its original configuration: Animal=Dragon, Colour=Green, Strength=10 -> reassigned metadata_id=A1
note

Immutable's system monitors the metadata for each asset in a collection and auto-identifies which assets have the same metadata; assigning those assets the same metadata_id.

Game studios do not set metadata_id themselves, they are generated by Immutable and can be identified through the nft endpoint.

How to trigger a metadata refresh?

To update the Blockchain Data API with the changes made to an existing asset the following steps should be followed.

When updating metadata, please remember to post the entire assets metadata when performing a refresh, not just the changed attributes. Submitting only the amended attributes will remove the metadata value you do not submit.

tip

If you have deployed your collection manually (i.e. not used Immutable's Hub to deploy a preset contract), you must link the collection to your Immutable Hub account.

The following tutorial will guide you through this process.

Refresh the metadata of a specific or list of NFTs via token_id

When initiating a metadata refresh request by referencing a specific or array of token_id, you will reindex the metadata of the specified tokens.

10 token_id can be present in a single metadata refresh batch update.

Here's an example of how you can execute this process:

Request parameters

ParameterDescriptionRequired
chainNameString representing the name of the chain.
Testnet: imtbl-zkevm-testnet
Mainnet: imtbl-zkevm-mainnet
Yes
contractAddressThe contract address of the ERC721 collectionYes
newNameThe new name of the NFT you are assigningYes
apiKeySecret key to your environment. Follow this guide to set yours upYes
publishableKeyPublic key to your environment. Follow this guide to set yours upYes

Use the following parameters in your function if you want to update the "name" property of a particular NFT:

import { config, blockchainData } from '@imtbl/sdk';

const API_KEY = 'YOUR_SECRET_API_KEY';
const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY';

const client = new blockchainData.BlockchainData({
baseConfig: {
environment: config.Environment.PRODUCTION,
apiKey: API_KEY,
publishableKey: PUBLISHABLE_KEY,
},
});

const refreshNFTMetadata = async (
client: blockchainData.BlockchainData,
chainName: string,
contractAddress: string,
newName: string
) => {
const nftMetadata: blockchainData.Types.RefreshMetadataByTokenID[] = [
{
name: newName,
animation_url: null,
image: null,
external_url: null,
youtube_url: null,
description: null,
attributes: [
{
trait_type: 'Power',
value: 'Happy',
},
],
token_id: '1',
},
];

const updatedNFT = await client.refreshNFTMetadata({
chainName,
contractAddress,
refreshNFTMetadataByTokenIDRequest: {
nft_metadata: nftMetadata,
},
});
};

The result will return the rate limit details informing how many refreshes are available for a period of time

Example response

{
"imx_refreshes_limit": "10000",
"imx_refresh_limit_reset": "2023-01-02 15:04:05",
"imx_remaining_refreshes": "9000",
"retry_after": "2-seconds"
}
💡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.

After this operation, the nft endpoint will accurately represent the updated metadata for all NFTs affected by this change. Additionally, the metadata refresh endpoint will reflect the new metadata attributes associated with the modified metadata_id.

Refresh the metadata for a stack of NFTs via metadata_id

caution

Updating metadata by metadata_id is not widely supported by Immutable's ecosystem partners, including marketplaces.

Immutable is enhancing this product to improve accessibility. Please check back on this page for updates.

When initiating a metadata refresh request by referencing a specific metadata_id, you will reindex all NFTs within the associated collection. This process can apply to a single asset or an entire stack of assets, making it the most efficient way to update the Blockchain Data API indexer when a group of NFTs undergo attribute changes.

10 metadata_id can be present in a single metadata refresh batch update.

Here's an example of how you can execute this process:

Use the following parameters in your function if you want to update the stacked metadata identified by `metadataID`:

import { blockchainData } from '@imtbl/sdk';

const refreshStackedMetadata = async (
client: blockchainData.BlockchainData,
chainName: string,
contractAddress: string,
newName: string
) => {
const updatedMetadata = await client.refreshStackedMetadata({
chainName,
contractAddress,
refreshMetadataByIDRequest: {
metadata: [
{
name: newName,
animation_url: null,
image: null,
external_url: null,
youtube_url: null,
description: null,
attributes: [],
metadata_id: '1',
},
],
},
});
};

The result will return the rate limit details informing how many refreshes are available for a period of time

Metadata refresh limits

Metadata refresh calls can be made by an individual project environment (i.e. game) at the following freqency.

Resource or operationLimit
Total number of NFTs updated677 per minute
Each NFT metadata refresh requestUp to 250 token IDs per request
Total NFT metadata size228 KiB per request
Total number of metadata stacks updated677 per minute
Each metadata stack refresh requestUp to 10 metadata stack IDs per request

Tip: If metadata_ids are used the number of NFTs updated per minutes can be significantly increased.

Also checkout default API rate limits.

How do I know if my NFTs metadata has been updated?

Metadata refresh requests are asynchronous. This means that the API will validate the incoming request and reject it if it is invalid. However, the metadata will be updated by a different workflow at a later point in time. Once the metadata for a given NFT is updated, the changes will be reflected in the nft endpoint. The metadata_synced_at field represents the most recent time of when the metadata for the NFT was updated.

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us