getNFTMetadata
Gets the metadata associated with a given NFT.
This endpoint is supported on the following chains and networks:
  • Ethereum: Mainnet, Rinkeby, Kovan, Goerli, Ropsten
  • Polygon: Mainnet and Mumbai
  • Flow: Mainnet and Testnet (see docs here)
To see chain support across all features, check out the feature matrix.

Parameters

  • contractAddress: [string] address of NFT contract
  • tokenId: [integer or hexadecimal] Id for NFT
  • tokenType : [string] (optional) "ERC721" or "ERC1155"; specifies type of token to query for
API requests will perform faster if tokenType is specified!

Returns

  • JSON Object containing the following fields and potentially more fields.
    • contract: contract for returned NFT
      • address: address of NFT contract
    • id
      • tokenId: Id for NFT (integer or hexadecimal, depending on parameter tokenId type)
      • tokenMetadata
        • tokenType: "ERC721" or "ERC1155"
    • tokenUri:
      • raw: uri representing the location of the NFT's original metadata blob. This is a backup for you to parse when the metadata field is not automatically populated.
      • gateway: public gateway uri for the raw uri above.
    • media:
      • raw: uri representing the location of the NFT media asset. This is a backup for you to parse when the metadata field is not automatically populated.
      • gateway: public gateway uri for the raw asset above.
      NOTE: Where possible, Alchemy-hosted NFT media are used in the gateway field and feature a Cloudinary URL for faster loading times and can be configured for image re-sizing. For more info on using Alchemy-hosted media, see this doc.
    • metadata: relevant metadata for NFT contract. This is useful for viewing image url, traits, etc. without having to follow the metadata url in tokenUri to parse manually.
      • image: URL to the NFT asset image. Can be standard URLs pointing to images on conventional servers, IPFS, or Arweave. Most types of images (SVGs, PNGs, JPEGs, etc.) are supported by NFT marketplaces.
      • external_url: The image URL that appears alongside the asset image on NFT platforms.
      • background_color: Background color of the NFT item. Usually must be defined as a six-character hexadecimal.
      • nameName of the NFT asset.
      • description: human-readable description of the NFT asset. (Markdown is supported/rendered on OpenSea and other NFT platforms)
      • attributes: traits/attributes/characteristics for each NFT asset.
      For more info on NFT responses: check out the NFT API FAQ.
    • timeLastUpdated: ISO timestamp of the last cache refresh for the information returned in the metadata field.
    • error: A string describing a particular reason that we were unable to fetch complete metadata for the NFT. See the Handling Errors section for a complete list of potential errors.
NOTE: To parse and view an NFT's media asset, use either the gatewayURI within themedia objector theexternal_urlwithin metadataobject. Visit the FAQ for more info on IPFS gateways. Select NFT contracts may not have metadata specified by their creator. You may need to parse the response on a case-by-case basis.

Example

The example below is for Ethereum Mainnet. If you are using Polygon you'll need to use your polygon endpoint instead: https://polygon-mainnet.g.alchemy.com/nft/v2/your-api-key/getNFTs...

Request

Alchemy SDK
Fetch (JS)
Axios (JS)
Postman
Curl
1
// Github: https://github.com/alchemyplatform/alchemy-sdk-js
2
// Setup: npm install @alch/alchemy-sdk
3
import { Network, initializeAlchemy, getNftMetadata } from "@alch/alchemy-sdk";
4
5
// Optional Config object, but defaults to demo api-key and eth-mainnet.
6
const settings = {
7
apiKey: "demo", // Replace with your Alchemy API Key.
8
network: Network.ETH_MAINNET, // Replace with your network.
9
maxRetries: 10,
10
};
11
12
const alchemy = initializeAlchemy(settings);
13
14
// Print total NFT count returned in the response:
15
const nftMetadata = await getNftMetadata(
16
alchemy,
17
"0x5180db8F5c931aaE63c74266b211F580155ecac8",
18
"1590"
19
);
20
console.log(nftMetadata);
21
Copied!
1
import fetch from 'node-fetch';
2
3
var requestOptions = {
4
method: 'GET',
5
redirect: 'follow'
6
};
7
8
const apiKey = "demo"
9
const baseURL = `https://eth-mainnet.alchemyapi.io/nft/v2/${apiKey}/getNFTMetadata`;
10
const contractAddr = "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d";
11
const tokenId = "2";
12
const tokenType = "erc721";
13
const fetchURL = `${baseURL}?contractAddress=${contractAddr}&tokenId=${tokenId}&tokenType=${tokenType}`;
14
15
fetch(fetchURL, requestOptions)
16
.then(response => response.json())
17
.then(response => JSON.stringify(response, null, 2))
18
.then(result => console.log(result))
19
.catch(error => console.log('error', error));
Copied!
1
import axios from 'axios';
2
3
// replace with your Alchemy api key
4
const apiKey = "demo";
5
const baseURL = `https://eth-mainnet.alchemyapi.io/nft/v2/${apiKey}/getNFTMetadata`;
6
const contractAddr = "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d";
7
const tokenId = "2";
8
const tokenType = "erc721";
9
10
var config = {
11
method: 'get',
12
url: `${baseURL}?contractAddress=${contractAddr}&tokenId=${tokenId}&tokenType=${tokenType}`,
13
headers: { }
14
};
15
16
axios(config)
17
.then(response => console.log(JSON.stringify(response.data, null, 2)))
18
.catch(error => console.log(error));
Copied!
1
URL: https://eth-mainnet.alchemyapi.io/nft/v2/demo/getNFTMetadata?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&tokenId=2&tokenType=erc721
2
RequestType: GET
Copied!
1
curl 'https://eth-mainnet.alchemyapi.io/nft/v2/demo/getNFTMetadata?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&tokenId=2&tokenType=erc721'
Copied!
If you're having trouble running requests via the Alchemy SDK, Fetch, or Axios, please refer to: NFT API Quickstart Guide

Response

1
{
2
contract: { address: '0x5180db8f5c931aae63c74266b211f580155ecac8' },
3
id: { tokenId: '1590', tokenMetadata: { tokenType: 'ERC721' } },
4
title: 'balsa vault',
5
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!',
6
tokenUri: {
7
raw: 'ipfs://QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB/1590.json',
8
gateway: 'https://ipfs.io/ipfs/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB/1590.json'
9
},
10
media: [ { uri: [Object] } ],
11
metadata: {
12
image: 'https://cryptocoven.s3.amazonaws.com/a7875f5758f85544dcaab79a8a1ca406.png',
13
external_url: 'https://www.cryptocoven.xyz/witches/1590',
14
background_color: '',
15
coven: {
16
skills: [Object],
17
name: 'balsa vault',
18
description: [Object],
19
styles: [Array],
20
id: 1590,
21
type: 'necromancer',
22
hash: 'a7875f5758f85544dcaab79a8a1ca406',
23
birthChart: [Object]
24
},
25
name: 'balsa vault',
26
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!',
27
attributes: [
28
[Object], [Object], [Object],
29
[Object], [Object], [Object],
30
[Object], [Object], [Object],
31
[Object], [Object], [Object],
32
[Object], [Object], [Object],
33
[Object], [Object], [Object],
34
[Object], [Object], [Object],
35
[Object], [Object], [Object],
36
[Object], [Object]
37
]
38
},
39
timeLastUpdated: '2022-01-25T07:41:32.003Z'
40
}
41
Copied!