NFT API

NFT API Quickstart

Go from zero to hero with the Alchemy NFT API. Learn how to query NFT data, then dive into some fun tutorials!
Don't have an API key?

Start using the NFT API in your app today. Get started for free

Getting Started Instructions

Follow along with the steps below to get started with the NFT API:

  1. Choose a package manager

  2. Set up your repo

  3. Choose a library

    1. Fetch
    2. Axios

1. Choose a package manager

For this guide, we will be using npm or yarn as our package manager if you choose to use axios.

npm

To get started with npm, follow the documentation to install Node.js and npm for your operating system: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm

yarn

To get started with yarn, follow these steps: https://classic.yarnpkg.com/lang/en/docs/install

2. Set up your repo

npm

Open up a terminal, and from the command line, create a new repository to hold your quickstart scripts. We’ll also initialize the repo as an npm project.

shell
$mkdir alchemy-nft-api
>cd alchemy-nft-api
>npm init --yes

yarn

shell
$mkdir alchemy-nft-api
>cd alchemy-nft-api
>yarn init --yes

Since we’ll be using import syntax to load ES6 modules, add 'type': 'module' to your package.json file:

See this discussion for more context.

3. Choose a Library

a) Fetch

You can easily interact with Alchemy’s NFT API using simple fetch requests. No additional dependencies required with Node.js 18+.

Demo Script

View the demo script on GitHub

In your alchemy-nft-api directory, you can create a new file called nft-api-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:

shell
$touch nft-api-script.js

and then paste the following code snippet into the file:

nft-api-script.js
1// Replace with your Alchemy API Key
2const apiKey = "demo";
3const baseURL = `https://eth-mainnet.g.alchemy.com/nft/v3/${apiKey}`;
4
5async function getNFTData() {
6 try {
7 // The wallet address we want to query for NFTs:
8 const ownerAddr = "vitalik.eth";
9 console.log("fetching NFTs for address:", ownerAddr);
10 console.log("...");
11
12 // Get NFTs for owner
13 const nftsResponse = await fetch(`${baseURL}/getNFTsForOwner?owner=${ownerAddr}&pageSize=5`);
14 const nftsData = await nftsResponse.json();
15
16 console.log("number of NFTs found:", nftsData.totalCount);
17 console.log("...");
18
19 // Print contract address and tokenId for each NFT:
20 for (const nft of nftsData.ownedNfts) {
21 console.log("===");
22 console.log("contract address:", nft.contract.address);
23 console.log("token ID:", nft.tokenId);
24 }
25 console.log("===");
26
27 // Fetch metadata for a particular NFT:
28 console.log("fetching metadata for a Crypto Coven NFT...");
29 const contractAddress = "0x5180db8F5c931aaE63c74266b211F580155ecac8";
30 const tokenId = "1590";
31
32 const metadataResponse = await fetch(
33 `${baseURL}/getNFTMetadata?contractAddress=${contractAddress}&tokenId=${tokenId}`
34 );
35 const response = await metadataResponse.json();
36
37 // Print some commonly used fields:
38 console.log("NFT name: ", response.name || response.title);
39 console.log("token type: ", response.tokenType);
40 console.log("tokenUri: ", response.tokenUri);
41 console.log("image url: ", response.image?.originalUrl || response.rawMetadata?.image);
42 console.log("time last updated: ", response.timeLastUpdated);
43 console.log("===");
44
45 } catch (error) {
46 console.error('Request failed:', error.message);
47 }
48}
49
50getNFTData();

From your command line, you can execute the script with:

shell
$node nft-api-script.js

You should see output like this:

shell
$fetching NFTs for address: vitalik.eth
>...
>number of NFTs found: 516
>...
>===
>contract address: 0x000386e3f7559d9b6a2f5c46b4ad1a9587d59dc3
>token ID: 29
>===
>contract address: 0x000386e3f7559d9b6a2f5c46b4ad1a9587d59dc3
>token ID: 238
>===
>...........
>===
>fetching metadata for a Crypto Coven NFT...
>NFT name: balsa vault
>token type: ERC721
>tokenUri: https://alchemy.mypinata.cloud/ipfs/QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm/1590.json
>image url: https://cryptocoven.s3.amazonaws.com/a7875f5758f85544dcaab79a8a1ca406.png
>time last updated: 2022-06-23T06:48:33.229Z
>===

b) Axios

axios is a promise-based HTTP client for the browser and Node.js, which allows us to make a raw request to the Alchemy API.

See the documentation for more info: https://www.npmjs.com/package/axios

Installation

Run the following command to install axios with npm and `yarn

$npm install axios

Demo Script

View the demo script on GitHub

In your alchemy-nft-api directory, you can create a new file called axios-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command.

shell
$touch axios-script.js

and then paste the following code snippet in to explore the getNFTs or getNFTMetadata methods:

1// alchemy-nft-api/axios-script.js
2import axios from 'axios';
3
4// Replace with your Alchemy API key:
5const apiKey = "demo";
6const baseURL = `https://eth-mainnet.g.alchemy.com/nft/v3/${apiKey}/getNFTsForOwner/`;
7// Replace with the wallet address you want to query for NFTs:
8const ownerAddr = "0xF5FFF32CF83A1A614e15F25Ce55B0c0A6b5F8F2c";
9const pageSize = 2;
10
11// Construct the axios request:
12var config = {
13 method: 'get',
14 url: `${baseURL}?owner=${ownerAddr}&pageSize=${pageSize}`
15};
16
17// Make the request and print the formatted response:
18axios(config)
19.then(response => console.log(JSON.stringify(response.data, null, 2)))
20.catch(error => console.log(error));

From your command line, you can execute the script with:

shell
$node axios-script.js

Your output should look like the following:

1alchemy-nft-api % node axios-script.js
2{
3"ownedNfts": [
4{
5"contract": {
6"address": "0x000386E3F7559d9B6a2F5c46B4aD1A9587D59Dc3",
7"name": "Bored Ape Nike Club",
8"symbol": "BANC",
9"totalSupply": null,
10"tokenType": "ERC721",
11"contractDeployer": "0x51D7D428041E23ef51422e110dfEfF906e821CFe",
12"deployedBlockNumber": 14276343,
13"openSeaMetadata": {
14"floorPrice": null,
15"collectionName": "BoredApeNikeClub",
16"collectionSlug": "bored-ape-nike-club-v2",
17"safelistRequestStatus": "not_requested",
18"imageUrl": "https://i.seadn.io/gae/yJ9DgXqjRwgdCkrQmHj7krCbixM8fPVAyYJWJ5NHXap1L0c3QL5MPvrNT0QDINIStGOK857lOvab8MpNQS9X4pkHPktmhVmN82qoVw?w=500&auto=format",
19"description": "COUNTDOWN OVER. MINTING LIVE.\n\n[Mint on the website.](https://nikemetaverse.xyz)\n",
20"externalUrl": "https://nikemetaverse.xyz",
21"twitterUsername": null,
22"discordUrl": null,
23"bannerImageUrl": "https://i.seadn.io/gae/i84LsC2dtbF5I3YiuaXzzfvSijlBI-ZJ8UEta04Ukl4V57Uoj0ZGw8tNyuPdwrF7N5pclyzdqSJjxHZ65z4G5jQrVRK_DHUMVrzTYQ?w=500&auto=format",
24"lastIngestedAt": "2023-10-30T07:13:52.000Z"
25},
26"isSpam": true,
27"spamClassifications": [
28"OwnedByMostHoneyPots",
29"Erc721TooManyOwners",
30"Erc721TooManyTokens",
31"NoSalesActivity",
32"HighAirdropPercent",
33"HighHoneyPotPercent",
34"HoneyPotsOwnMultipleTokens"
35]
36},
37"tokenId": "1",
38"tokenType": "ERC721",
39"name": null,
40"description": null,
41"tokenUri": "http://api.nikeapenft.xyz/ipfs/1",
42"image": {
43"cachedUrl": null,
44"thumbnailUrl": null,
45"pngUrl": null,
46"contentType": null,
47"size": null,
48"originalUrl": null
49},
50"raw": {
51"tokenUri": "http://api.nikeapenft.xyz/ipfs/1",
52"metadata": {},
53"error": null
54},
55"collection": {
56"name": "BoredApeNikeClub",
57"slug": "bored-ape-nike-club-v2",
58"externalUrl": "https://nikemetaverse.xyz",
59"bannerImageUrl": "https://i.seadn.io/gae/i84LsC2dtbF5I3YiuaXzzfvSijlBI-ZJ8UEta04Ukl4V57Uoj0ZGw8tNyuPdwrF7N5pclyzdqSJjxHZ65z4G5jQrVRK_DHUMVrzTYQ?w=500&auto=format"
60},
61"mint": {
62"mintAddress": null,
63"blockNumber": null,
64"timestamp": null,
65"transactionHash": null
66},
67"owners": null,
68"timeLastUpdated": "2023-11-06T04:34:38.880Z",
69"balance": "26",
70"acquiredAt": {
71"blockTimestamp": null,
72"blockNumber": null
73}
74},
75],
76"totalCount": 26620,
77"validAt": {
78"blockNumber": 18513471,
79"blockHash": "0x49376e3ea0d07b4b557521832ac2f52213b12bf912087ac1fe9f04c9899d221b",
80"blockTimestamp": "2023-11-06T14:15:23Z"
81},
82"pageKey": "MHgwMDAzODZlM2Y3NTU5ZDliNmEyZjVjNDZiNGFkMWE5NTg3ZDU5ZGMzOjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMjpmYWxzZQ=="
83}