API Reference
Alchemy Login

getNftMetadata - SDK

Get the NFT metadata associated with the provided parameters.

Don’t have an API key?

Start using this method in your app today.

Get started for free

Description

Get the NFT metadata associated with the provided parameters.

Parameters

NameTypeDescription
contractAddressstringThe contract address of the NFT.
tokenIdstringToken id of the NFT.
optionsobjectOptions for the request. A null object should still be passed in the params if no options are given for the request.

options paramters

ParameterTypeDeescription
tokenType?objectOptional field to specify the type of token to speed up the query. Available options include: [ERC721 = "ERC721", ERC1155 = "ERC1155", UNKNOWN = "UNKNOWN"]
tokenUriTimeoutInMs?numberNo set timeout by default - When metadata is requested, this parameter is the timeout (in milliseconds) for the website hosting the metadata to respond. If you want to only access the cache and not live fetch any metadata for cache misses then set this value to 0.
refreshCache?booleanWhether to refresh the metadata for the given NFT token before returning the response. Defaults to false for faster response times.

Response

PropertyTypeDescription
Promise<Nft>array of objectsAn array of objects containing nft metadata.

Nft response object parameters

PropertyTypeDescription
contractobjectThe NFT's underlying contract and relevant contract metadata.

Parameters in the contract include:

1. contractDeployer?: string The address that deployed the NFT contract.

2. name: string The name of the contract.

3. symbol: string The symbol of the contract.

4. totalSupply: string The number of NFTs in the contract as an integer string. This field is only available on ERC-721 contracts.

5. tokenType: string The type of the token in the contract. e.g, ERC721, ERC1155, UNKNOWN
}
titlestringThe NFT title.
descriptionstringThe NFT description.
timeLastUpdatedstringWhen the NFT was last updated in the blockchain. Represented in ISO-8601 format.
metadataErrorstring | undefinedHolds an error message if there was an issue fetching metadata.
rawMetadataobjectThe raw metadata fetched from the metadata URL specified by the NFT. The field is undefined if Alchemy was unable to fetch metadata.
tokenURIobjectURIs for accessing the NFT's metadata blob.
mediaarrayURIs for accessing the NFT's media assets.
spamInfoobjectDetailed information on why an NFT was classified as spam.

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

Request

// 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 () => {
    const contractAddress = "0x5180db8F5c931aaE63c74266b211F580155ecac8";
    const tokenId = "1590";

    // call the method
    let response = await alchemy.nft.getNftMetadata(contractAddress, tokenId, {});

    // logging the response to the console
    console.log(response)
};

main();

Response

[
  {
    contract: {
      address: '0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d',
      name: 'BoredApeYachtClub',
      symbol: 'BAYC',
      totalSupply: '10000',
      tokenType: 'ERC721',
      openSea: [Object],
      contractDeployer: '0xaba7161a7fb69c88e16ed9f455ce62b791ee4d03',
      deployedBlockNumber: 12287507
    },
    tokenId: '3',
    tokenType: 'ERC721',
    title: '',
    description: '',
    timeLastUpdated: '2023-02-26T08:28:13.584Z',
    metadataError: undefined,
    rawMetadata: {
      image: 'ipfs://QmYxT4LnK8sqLupjbS6eRvu1si7Ly2wFQAqFebxhWntcf6',
      attributes: [Array]
    },
    tokenUri: {
      gateway: 'https://ipfs.io/ipfs/QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/3',
      raw: 'ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/3'
    },
    media: [ [Object] ],
    spamInfo: undefined
  },
  {
    contract: {
      address: '0x8a90cab2b38dba80c64b7734e58ee1db38b8992e',
      name: 'Doodles',
      symbol: 'DOODLE',
      totalSupply: '10000',
      tokenType: 'ERC721',
      openSea: [Object],
      contractDeployer: '0x2b3ab8e7bb14988616359b78709538b10900ab7d',
      deployedBlockNumber: 13430097
    },
    tokenId: '4',
    tokenType: 'ERC721',
    title: 'Doodle #4',
    description: 'A community-driven collectibles project featuring art by Burnt Toast. Doodles come in a joyful range of colors, traits and sizes with a collection size of 10,000. Each Doodle allows its owner to vote for experiences and activations paid for by the Doodles Community Treasury. Burnt Toast is the working alias for Scott Martin, a Canadian–based illustrator, designer, animator and muralist.',
    timeLastUpdated: '2023-02-26T08:28:13.658Z',
    metadataError: undefined,
    rawMetadata: {
      image: 'ipfs://QmcyuFVLbfBmSeQ9ynu4dk67r97nB1abEekotuVuRGWedm',
      name: 'Doodle #4',
      description: 'A community-driven collectibles project featuring art by Burnt Toast. Doodles come in a joyful range of colors, traits and sizes with a collection size of 10,000. Each Doodle allows its owner to vote for experiences and activations paid for by the Doodles Community Treasury. Burnt Toast is the working alias for Scott Martin, a Canadian–based illustrator, designer, animator and muralist.',
      attributes: [Array]
    },
    tokenUri: {
      gateway: 'https://ipfs.io/ipfs/QmPMc4tcBsMqLRuCQtPmPe84bpSjrC3Ky7t3JWuHXYB4aS/4',
      raw: 'ipfs://QmPMc4tcBsMqLRuCQtPmPe84bpSjrC3Ky7t3JWuHXYB4aS/4'
    },
    media: [ [Object] ],
    spamInfo: undefined
  }
]
admin@Admins-MBP Alchem % node index.js
{
  contract: {
    address: '0x5180db8f5c931aae63c74266b211f580155ecac8',
    name: 'Crypto Coven',
    symbol: 'WITCH',
    totalSupply: undefined,
    tokenType: 'ERC721',
    openSea: {
      floorPrice: 0.124988,
      collectionName: 'Crypto Coven',
      safelistRequestStatus: 'verified',
      imageUrl: 'https://i.seadn.io/gae/E8MVasG7noxC0Fa_duhnexc2xze1PzT1jzyeaHsytOC4722C2Zeo7EhUR8-T6mSem9-4XE5ylrCtoAsceZ_lXez_kTaMufV5pfLc3Fk?w=500&auto=format',
      description: "it's the season of the witch. ????",
      externalUrl: 'https://www.cryptocoven.xyz/',
      twitterUsername: 'crypto_coven',
      discordUrl: 'https://discord.gg/cryptocoven',
      lastIngestedAt: '2023-02-21T15:08:44.000Z'
    },
    contractDeployer: '0xac9d54ca08740a608b6c474e5ca07d51ca8117fa',
    deployedBlockNumber: 13547115
  },
  tokenId: '1590',
  tokenType: 'ERC721',
  title: 'balsa vault',
  description: 'You are a WITCH with eyes that hold eons. You write poems filled with charms. Your magic spawns from a few hours of sleep. You arch your back into a bridge between the living and the dead. SHINE!',
  timeLastUpdated: '2023-02-26T04:08:28.725Z',
  metadataError: undefined,
  rawMetadata: {
    image: 'https://cryptocoven.s3.amazonaws.com/a7875f5758f85544dcaab79a8a1ca406.png',
    external_url: 'https://www.cryptocoven.xyz/witches/1590',
    background_color: '',
    coven: {
      skills: [Object],
      name: 'balsa vault',
      description: [Object],
      styles: [Array],
      id: 1590,
      type: 'necromancer',
      hash: 'a7875f5758f85544dcaab79a8a1ca406',
      birthChart: [Object]
    },
    name: 'balsa vault',
    description: 'You are a WITCH with eyes that hold eons. You write poems filled with charms. Your magic spawns from a few hours of sleep. You arch your back into a bridge between the living and the dead. SHINE!',
    attributes: [
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object]
    ]
  },
  tokenUri: {
    gateway: 'https://alchemy.mypinata.cloud/ipfs/QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm/1590.json',
    raw: 'ipfs://QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm/1590.json'
  },
  media: [
    {
      gateway: 'https://nft-cdn.alchemy.com/eth-mainnet/d19db83206d00d210696cba9be86f754',
      thumbnail: 'https://res.cloudinary.com/alchemyapi/image/upload/thumbnailv2/eth-mainnet/d19db83206d00d210696cba9be86f754',
      raw: 'https://cryptocoven.s3.amazonaws.com/a7875f5758f85544dcaab79a8a1ca406.png',
      format: 'png',
      bytes: 2724759
    }
  ],
  spamInfo: undefined
}

Code Sandbox

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

Use Cases

Here are some potential use cases for the getNftMetadata function:

  • Displaying NFT information: When a user wants to view information about a specific NFT, such as its name, description, image, or other attributes, getNftMetadata can be called to retrieve this information from the NFT metadata.

  • NFT marketplaces: NFT marketplaces can use getNftMetadata to display information about NFTs that are available for sale or auction. This information can help potential buyers make informed decisions about which NFTs to purchase.

  • Verification: getNftMetadata can be used to verify the authenticity of an NFT. If the metadata associated with an NFT matches the expected values, then it is more likely to be a genuine NFT.

Related Methods

Here are the methods related to getNftMetadata:

ReadMe