NFT API Quickstart Guide

For this Javascript quickstart guide, we recommend using alchemy-web3, a module that allows you to more easily interact with Alchemy APIs. The alchemy-web3 SDK give you websocket support and other benefits right out of the box! Fetch or Axios are two alternative modules that also allow you to make HTTP requests.
Common setup steps
You should start with these steps before choosing any of the modules below.
Choose a package manager (npm or yarn)
For this guide we will be using npm  or yarn as our package manager to install either alchemy-web3, fetch, or 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​
Set up your repo (npm or yarn)
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.
1
mkdir alchemy-nft-api
2
cd alchemy-nft-api
3
npm init --yes
Copied!
yarn
1
mkdir alchemy-nft-api
2
cd alchemy-nft-api
3
yarn init --yes
Copied!
Support import syntax
Since we'll be using import syntax to load ES6 modules, add 'type': 'module' to your package.json file:
1
// package.json
2
{
3
  ...
4
  "type": "module"
5
}
Copied!
See this discussion for more context: https://stackoverflow.com/questions/61401475/why-is-type-module-in-package-json-file​
Alchemy Web3 SDK (Recommended)
You can install the alchemy-web3 module to easily interact with Alchemy APIs. We highly recommend using the alchemy-web3 sdk because you also get websocket support, retries, and other benefits without the complexity!
For full documentation on alchemy-web3, check the github repo: https://github.com/alchemyplatform/alchemy-web3​
Installation
npm
yarn
Run the following command to install alchemy-web3 with npm
1
npm install @alch/alchemy-web3
Copied!
Run the following command to install alchemy-web3 with yarn
1
yarn add @alch/alchemy-web3
Copied!
Usage
nft-api-javascript-scripts/alchemy-web3-script.js at main · alchemyplatform/nft-api-javascript-scripts
GitHub
In your alchemy-nft-api directory, you can create a new file called alchemy-web3-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:
1
touch alchemy-web3-script.js
Copied!
and then paste the following code snippet into the file:
1
// alchemy-nft-api/alchemy-web3-script.js
2
import { createAlchemyWeb3 } from "@alch/alchemy-web3";
3
​
4
// Replace with your Alchemy api key:
5
const apiKey = "demo";
6
​
7
// Initialize an alchemy-web3 instance:
8
const web3 = createAlchemyWeb3(
9
  `https://eth-mainnet.alchemyapi.io/v2/${apiKey}`,
10
);
11
​
12
// The wallet address we want to query for NFTs:
13
const ownerAddr = "0xC33881b8FD07d71098b440fA8A3797886D831061";
14
const nfts = await web3.alchemy.getNfts({
15
  owner: ownerAddr
16
})
17
​
18
// Print owner's wallet address:
19
console.log("fetching NFTs for address:", ownerAddr);
20
console.log("...");
21
​
22
// Print total NFT count returned in the response:
23
console.log("number of NFTs found:", nfts.totalCount);
24
console.log("...");
25
​
26
// Print contract address and tokenId for each NFT:
27
for (const nft of nfts.ownedNfts) {
28
  console.log("===");
29
  console.log("contract address:", nft.contract.address);
30
  console.log("token ID:", nft.id.tokenId);
31
}
32
console.log("===");
33
​
34
// Fetch metadata for a particular NFT:
35
console.log("fetching metadata for a crypto coven NFT...");
36
const response = await web3.alchemy.getNftMetadata({
37
  contractAddress: "0x5180db8F5c931aaE63c74266b211F580155ecac8",
38
  tokenId: "1590"
39
})
40
​
41
// Uncomment this line to see the full api response:
42
// console.log(metadata);
43
​
44
// Print some commonly used fields:
45
console.log("NFT name: ", response.title);
46
console.log("token type: ", response.id.tokenMetadata.tokenType);
47
console.log("tokenUri: ", response.tokenUri.gateway);
48
console.log("image url: ", response.metadata.image);
49
console.log("time last updated: ", response.timeLastUpdated);
50
console.log("===");
Copied!
From your command line, you can execute the script with:
1
node alchemy-web3-script.js
Copied!
You should see output like this:
1
alchemy-nft-api % node alchemyweb3-script.js
2
fetching NFTs for address: 0xC33881b8FD07d71098b440fA8A3797886D831061
3
...
4
number of NFTs found: 1
5
...
6
===
7
contract address: 0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85
8
token ID: 0x3ee4ed8824659deea1bb8fa6d4090b11d263417704c0a0fbc78fa8c4fc177909
9
===
10
fetching metadata for a crypto coven NFT...
11
NFT name:  balsa vault
12
token type:  ERC721
13
tokenUri:  https://ipfs.io/ipfs/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB/1590.json
14
image url:  https://cryptocoven.s3.amazonaws.com/a7875f5758f85544dcaab79a8a1ca406.png
15
time last updated:  2022-01-25T07:41:32.003Z
16
===
Copied!
For full documentation on the available endpoints for alchemy-web3 sdk, check the github repo:
GitHub - alchemyplatform/alchemy-web3: Web3 client extended with Alchemy integration
GitHub
Javascript Fetch 
node-fetch a lightweight, common module that brings the Fetch API to Node.js and allows us to make our HTTP requests. 
See the documentation for more info: https://www.npmjs.com/package/node-fetch​
Installation
npm
yarn
Run the following command to install node-fetch with npm
1
npm install node-fetch
Copied!
Run the following command to install node-fetch with yarn
1
yarn add node-fetch
Copied!
Usage
nft-api-javascript-scripts/fetch-script.js at main · alchemyplatform/nft-api-javascript-scripts
GitHub
In your alchemy-nft-api directory, you can create a new file called fetch-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:
1
touch fetch-script.js
Copied!
and then paste the following code snippet into the file to explore the getNFTs method:
1
// alchemy-nft-api/fetch-script.js
2
import fetch from 'node-fetch';
3
​
4
// Setup request options:
5
var requestOptions = {
6
  method: 'GET',
7
  redirect: 'follow'
8
};
9
​
10
// Replace with your Alchemy API key:
11
const apiKey = "demo";
12
const baseURL = `https://eth-mainnet.alchemyapi.io/v2/${apiKey}/getNFTs/`;
13
// Replace with the wallet address you want to query:
14
const ownerAddr = "0xF5FFF32CF83A1A614e15F25Ce55B0c0A6b5F8F2c";
15
const fetchURL = `${baseURL}?owner=${ownerAddr}`;
16
​
17
// Make the request and print the formatted response:
18
fetch(fetchURL, requestOptions)
19
  .then(response => response.json())
20
  .then(response => JSON.stringify(response, null, 2))
21
  .then(result => console.log(result))
22
  .catch(error => console.log('error', error));
23
​
Copied!
From your command line, you can execute the script with:
1
node fetch-script.js
Copied!
Your output should look like the following:
1
{
2
  "ownedNfts": [
3
    {
4
      "contract": {
5
        "address": "0x0beed7099af7514ccedf642cfea435731176fb02"
6
      },
7
      "id": {
8
        "tokenId": "0x000000000000000000000000000000000000000000000000000000000000001c"
9
      },
10
      "balance": "1"
11
    },
12
    ......
13
    },
14
    {
15
      "contract": {
16
        "address": "0xc4c377565a4b9eb6e657c2422bd33b6e4859b041"
17
      },
18
      "id": {
19
        "tokenId": "0x01"
20
      },
21
      "balance": "1"
22
    }
23
  ],
24
  "totalCount": 12,
25
  "blockHash": "0x470e52bdaffff978b4a89b2cfb2b8a3f92ec523bffb4bdb3d9b656ff8be57f8d"
26
}
27
​
Copied!
For full documentation on the NFT API getNFTs method, check out the docs:
getNFTs
Now, in your alchemy-nft-api directory, let's now re-edit fetch-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:
1
touch fetch-script.js
Copied!
Paste the following code snippet into the file to explore the getNFTMetadata method:
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/v2/${demo}/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));
20
​
Copied!
From your command line, you can execute the script with:
1
node fetch-script.js
Copied!
Your output should look like the following:
1
{
2
  "contract": {
3
    "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
4
  },
5
  "id": {
6
    "tokenId": "2",
7
    "tokenMetadata": {
8
      "tokenType": "ERC721"
9
    }
10
  },
11
  "title": "",
12
  "description": "",
13
  "tokenUri": {
14
    "raw": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/2",
15
    "gateway": "https://ipfs.io/ipfs/QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/2"
16
  },
17
  "media": [
18
    {
19
      "uri": {
20
        "raw": "ipfs://QmcJYkCKK7QPmYWjp4FD2e3Lv5WCGFuHNUByvGKBaytif4",
21
        "gateway": "https://ipfs.io/ipfs/QmcJYkCKK7QPmYWjp4FD2e3Lv5WCGFuHNUByvGKBaytif4"
22
      }
23
    }
24
  ],
25
  "metadata": {
26
    "image": "ipfs://QmcJYkCKK7QPmYWjp4FD2e3Lv5WCGFuHNUByvGKBaytif4",
27
    "attributes": [
28
      {
29
        "value": "3d",
30
        "trait_type": "Eyes"
31
      },
32
      {
33
        "value": "Bored Cigarette",
34
        "trait_type": "Mouth"
35
      },
36
      {
37
        "value": "Robot",
38
        "trait_type": "Fur"
39
      },
40
      {
41
        "value": "Sea Captain's Hat",
42
        "trait_type": "Hat"
43
      },
44
      {
45
        "value": "Aquamarine",
46
        "trait_type": "Background"
47
      }
48
    ]
49
  },
50
  "timeLastUpdated": "2022-02-01T00:30:04.643Z"
51
}
52
​
Copied!
For full documentation on the NFT API getNFTMetadata method, check out the docs:
getNFTMetadata
Javascript 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
npm
yarn
Run the following command to install axios with npm
1
npm install axios
Copied!
Run the following command to install axios with yarn
1
yarn add axios
Copied!
Usage
nft-api-javascript-scripts/axios-script.js at main · alchemyplatform/nft-api-javascript-scripts
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. 
1
touch axios-script.js
Copied!
and then paste the following code snippet in to explore the getNFTs method
1
// alchemy-nft-api/axios-script.js
2
import axios from 'axios';
3
​
4
// Replace with your Alchemy API key:
5
const apiKey = "demo";
6
const baseURL = `https://eth-mainnet.alchemyapi.io/v2/${apiKey}/getNFTs/`;
7
// Replace with the wallet address you want to query for NFTs:
8
const ownerAddr = "0xF5FFF32CF83A1A614e15F25Ce55B0c0A6b5F8F2c";
9
​
10
// Construct the axios request:
11
var config = {
12
  method: 'get',
13
  url: `${baseURL}?owner=${ownerAddr}`
14
};
15
​
16
// Make the request and print the formatted response:
17
axios(config)
18
.then(response => console.log(JSON.stringify(response.data, null, 2)))
19
.catch(error => console.log(error));
Copied!
From your command line, you can execute the script with:
1
node axios-script.js
Copied!
Your output should look like the following:
1
alchemy-nft-api % node axios-script.js
2
{
3
  "ownedNfts": [
4
    {
5
      "contract": {
6
        "address": "0x049aba7510f45ba5b64ea9e658e342f904db358d"
7
      },
8
      "id": {
9
        "tokenId": "0x3651c7a73d3eea6a637f10a28ad1d8d296223e321b06626b2b4eac48eef4af4e"
10
      },
11
      "balance": "1"
12
    },
13
    ...
14
    {
15
      "contract": {
16
        "address": "0xf3e778f839934fc819cfa1040aabacecba01e049"
17
      },
18
      "id": {
19
        "tokenId": "0x00000000000000000000000000000000000000000000000000000000000060ed"
20
      },
21
      "balance": "1"
22
    }
23
  ],
24
  "totalCount": 36,
25
  "blockHash": "0x282c0c43a9eb14c0c42d72c3102421c76af27d9afa7f79cee595c4fec9e63535"
26
}
Copied!
For full documentation on the available NFT API method  getNFTs , check out the docs:
getNFTs
Now, in your alchemy-nft-api directory, let's now re-edit axios-script.js using your favorite file browser, code editor, or just directly in the terminal using the touch command like this:
1
touch axios-script.js
Copied!
and then paste the following code snippet in to explore the getNFTs method
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/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!
From your command line, you can execute the script with:
1
node axios-script.js
Copied!
Your output should look like the following:
1
{
2
  "contract": {
3
    "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
4
  },
5
  "id": {
6
    "tokenId": "2",
7
    "tokenMetadata": {
8
      "tokenType": "ERC721"
9
    }
10
  },
11
  "title": "",
12
  "description": "",
13
  "tokenUri": {
14
    "raw": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/2",
15
    "gateway": "https://ipfs.io/ipfs/QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/2"
16
  },
17
  "media": [
18
    {
19
      "uri": {
20
        "raw": "ipfs://QmcJYkCKK7QPmYWjp4FD2e3Lv5WCGFuHNUByvGKBaytif4",
21
        "gateway": "https://ipfs.io/ipfs/QmcJYkCKK7QPmYWjp4FD2e3Lv5WCGFuHNUByvGKBaytif4"
22
      }
23
    }
24
  ],
25
  "metadata": {
26
    "image": "ipfs://QmcJYkCKK7QPmYWjp4FD2e3Lv5WCGFuHNUByvGKBaytif4",
27
    "attributes": [
28
      {
29
        "value": "3d",
30
        "trait_type": "Eyes"
31
      },
32
      {
33
        "value": "Bored Cigarette",
34
        "trait_type": "Mouth"
35
      },
36
      {
37
        "value": "Robot",
38
        "trait_type": "Fur"
39
      },
40
      {
41
        "value": "Sea Captain's Hat",
42
        "trait_type": "Hat"
43
      },
44
      {
45
        "value": "Aquamarine",
46
        "trait_type": "Background"
47
      }
48
    ]
49
  },
50
  "timeLastUpdated": "2022-02-01T00:30:04.643Z"
51
}
52
​
Copied!
For full documentation on the available NFT API method  getNFTMetadata , check out the docs:
getNFTMetadata

NFT API FAQ

Handling errors

Last modified 2mo ago

Copy link

Contents

Common setup steps

Choose a package manager (npm or yarn)

Set up your repo (npm or yarn)

Support import syntax

Alchemy Web3 SDK (Recommended)