Skip to main content

Metadata refresh

This guide explains how to trigger a metadata refresh once an in-game asset is updated

Sections

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.

caution

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.

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.

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 or ERC1155 collectionYes
newNameThe new name of the NFT/SFT 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
refresh-nft-metadata.tsView on GitHub
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,
    },
  });
};

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.

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

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us