Metadata refresh
This guide explains how to trigger a metadata refresh once an in-game asset is updated
Immutable’s metadata refresh system is designed for Web3 gaming, offering performance advantages over traditional NFT platforms. However, Immutable does not listen for URI update events. You must trigger a Metadata Refresh for ecosystem-wide synchronization.
Immutable does not support URI events, if you update the metadata for an existing NFT you must push the metadata to Immutable Blockchain Data API (via our API or SDK).
What is a Metadata Refresh Call?
When an ERC721 (NFT) or ERC1155 (SFT) is initially minted, its metadata is automatically indexed by the Blockchain Data API. However, in-game assets often evolve through player actions, such as crafting or performance enhancements. These changes are not automatically updated across Immutable's ecosystem.
The metadata refresh service ensures that the entire ecosystem (especially marketplaces) is informed about the asset's evolution. This transparency benefits players, as they can accurately reflect any improvements when listing their assets on marketplaces.
All ERC721 and ERC1155 collections should have their metadata stored using the baseURI/token_id
format.
See here for more information how to implement.
Benefits of Immutable’s Metadata Push System
- No gas fees: Partners avoid gas fees for dynamic metadata updates via our API-based approach.
- NFaster updates: Metadata changes are reflected on Immutable’s marketplaces within ~8 seconds, ensuring ecosystem-wide synchronization.
- NHigher capacity: Pushing metadata to Immutable allows us to handle large volumes of updates without impacting gameplay performance. Crawling partner servers for metadata introduces latency.
- NGame stability: During periods of high gameplay and frequent metadata updates, relying on Immutable to handle metadata refreshes reduces the risk of backend instability for game studios.
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.
- Metadata Refresh by token_id
- Metadata Refresh by metadata_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
Parameter | Description | Required |
---|---|---|
chainName | String representing the name of the chain. Testnet: imtbl-zkevm-testnet Mainnet: imtbl-zkevm-mainnet | Yes |
contractAddress | The contract address of the ERC721 or ERC1155 collection | Yes |
newName | The new name of the NFT/SFT you are assigning | Yes |
apiKey | Secret key to your environment. Follow this guide to set yours up | Yes |
publishableKey | Public key to your environment. Follow this guide to set yours up | Yes |
- SDK
- API
import { blockchainData } from "@imtbl/sdk";
import { client } from "../lib";
export async function refreshNFTMetadata(
chainName: string,
contractAddress: string,
newName: string
): Promise<blockchainData.Types.MetadataRefreshRateLimitResult> {
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',
},
];
return await client.refreshNFTMetadata({
chainName,
contractAddress,
refreshNFTMetadataByTokenIDRequest: {
nft_metadata: nftMetadata,
},
});
};
Using Immutable's API you can refresh the metadata of a list of NFT/SFT with the following RefreshNFTMetadataByTokenID API call; which will produce a result in the below format.
POST /chains/{chain_name}/collections/{contract_address}/nfts/refresh-metadata
Example response
{
"imx_refreshes_limit": "10000",
"imx_refresh_limit_reset": "2023-01-02 15:04:05",
"imx_remaining_refreshes": "9000",
"retry_after": "2-seconds"
}
After this operation, the NFT endpoint will accurately represent the updated metadata for all NFTs/SFTs affected by this change. Additionally, the metadata refresh endpoint will reflect the new metadata attributes associated with the modified metadata_id
.
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.
metadata_id
can be used to update a stack of assets; this is significantly faster than updating each asset by token_id
.
For more information on metadata_id
see the following guide.
Performing a Metadata Refresh by metadata_id
?
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:
- SDK
- API
import { blockchainData } from '@imtbl/sdk';
import { client } from '../lib';
export async function refreshStackedMetadata(
chainName: string,
contractAddress: string,
newName: string
): Promise<blockchainData.Types.MetadataRefreshRateLimitResult> {
return 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',
},
],
},
});
};
Using Immutable's API you can refresh a stacked metadata identified by its `metadataID` with the following RefreshMetadataByID API call; which will produce a result in the below format.
POST /chains/{chain_name}/collections/{contract_address}/metadata/refresh-metadata
Example of Metadata Update Scenarios
The following table demonstrates how metadata_id
changes in different scenarios involving metadata updates:
Situation | Metadata Change | Metadata Refresh By | Asset After Refresh | Metadata ID |
---|---|---|---|---|
1 asset with unique metadata | Update metadata | token_id | Unique metadata | New metadata_id |
1 asset with unique metadata | Update metadata | token_id | Asset has metadata equal to a stack of assets assigned with metadata_id =X | Refreshed asset assigned metadata_id =X |
1 asset with unique metadata | Update metadata | metadata_id | Unique metadata | No change to metadata_id |
1 asset with unique metadata | Update metadata | metadata_id | Asset has metadata equal to a stack of assets assigned with metadata_id =X | Error generated. Cannot have 2 metadata_ids representing identical stacked assets |
100 assets sharing metadata | Change 1 asset's metadata | token_id | Unique metadata | New metadata_id |
100 assets sharing metadata | Change 1 asset's metadata | token_id | Asset has metadata equal to a stack of assets assigned with metadata_id =X | Refreshed asset assigned metadata_id =X |
100 assets sharing metadata | Change 100 assets' metadata | metadata_id | Unique metadata for stack | No change to metadata_id |
100 assets sharing metadata | Change 100 assets' metadata | metadata_id | Assets has metadata equal to a stack of assets assigned with metadata_id =X | Error 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:
- An unique asset has the following metadata: Animal=Dragon, Colour=Green, Strength=10 -> assigned
metadata_id
=A1 - This asset has its metadata updated to the following: Animal=Dragon, Colour=Red, Strength=10 -> assigned
metadata_id
=A2, no assets currently havemetadata_id
=A1 - This asset has its metadata updated back to its original configuration: Animal=Dragon, Colour=Green, Strength=10 -> reassigned
metadata_id
=A1
Game studios do not set metadata_id
themselves, they are generated by Immutable and can be identified through the NFT endpoint.
Metadata refresh limits
Metadata refresh calls can be made by an individual project environment (i.e. game) at the following freqency.
Resource or operation | Limit |
---|---|
Total number of NFTs updated | 677 per minute |
Each NFT metadata refresh request | Up to 250 token IDs per request |
Total NFT metadata size | 228 KiB per request |
Total number of metadata stacks updated | 677 per minute |
Each metadata stack refresh request | Up 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 assets 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/SFT 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/SFT was updated.