refreshContract - SDK

Triggers a metadata refresh of all NFTs in the provided contract address. This method is useful after an NFT collection is revealed.

Don’t have an API key?

Start using this method in your app today.

Triggers a metadata refresh of all NFTs in the provided contract address. This method is useful after an NFT collection is revealed.

Refreshes are queued on the Alchemy backend and may take time to fully process. To refresh the metadata for a specific token, use the refreshNftMetadata method instead.


contractAddressstringThe contract address of the NFT collection.


Promise<RefreshContractResult>objectThe refresh result response object.

RefreshContractResult response object parameters

contractAddressstringThe NFT contract address that was passed in to be refreshed.
refreshStatestringThe current state of the refresh request.
progressstring | nullPercentage of tokens currently refreshed, represented as an integer string. Field can be null if the refresh has not occurred.

Available options are:

The contract does not exist DOES_NOT_EXIST = "doesnot_exist",

_The contract has already been queued for refresh.
ALREADY_QUEUED = "alreadyqueued",

_The contract is currently being refreshed.
IN_PROGRESS = "inprogress",

_The contract refresh is complete.

FINISHED = "finished",

The contract refresh has been queued and await execution.
QUEUED = "queued",

The contract was unable to be queued due to an internal error.
QUEUE_FAILED = "queue_failed"

Example Request and Response

Prerequisite: You will need to install the Alchemy SDK before making requests with it.

The commands for installing it using npm or yarn are given below:

npm install alchemy-sdk
yarn add alchemy-sdk


// Imports the Alchemy SDK
const { Alchemy, Network } = require("alchemy-sdk");

// Configures the Alchemy SDK
const config = {
    apiKey: "alchemy-replit", // Replace with your API key
    network: Network.ETH_MAINNET, // Replace with your network

// Creates an Alchemy object instance with the config to use for making requests
const alchemy = new Alchemy(config);

const main = async () => {
    // define the contract address
    const address = "0x5180db8F5c931aaE63c74266b211F580155ecac8";

    //Call the method to return the refresh result response object
    const response = await alchemy.nft.refreshContract(address)

    //Logging the response to the console



  contractAddress: '0x5180db8f5c931aae63c74266b211f580155ecac8',
  refreshState: 'queued',
  progress: 0

Code Sandbox

You can test out the refreshContract method using the code sandbox below:

Use Cases

Here are some potential use cases for the refreshContract method:

  • Marketplace management: NFT marketplaces can use the refreshContract method to ensure that the data for a specific contract is up-to-date, including any changes to the contract's metadata or events. This information is crucial for ensuring that the marketplace accurately reflects the current state of the contract.

  • Contract management: Developers can use the refreshContract method to update the data for a contract they are developing. This can be useful for ensuring that the contract is functioning properly and for identifying any potential issues or bugs.

  • User interface updates: DApp developers can use the refreshContract method to update their user interfaces to reflect any changes to the contract's metadata or events. This can be useful for improving the user experience and ensuring that the DApp is always displaying the most accurate information.

Related Methods

Here are the methods related to refreshContract:

  • refreshNftMetadata: Refreshes the cached metadata for a provided NFT contract address and token id. Returns a boolean value indicating whether the metadata was refreshed.

  • searchContractMetadata: Search for a keyword across the metadata of all ERC-721 and ERC-1155 smart contracts.