Table of Contents

1. Introduction
2. Overview of Changes in NFT API V3
3. Migrating from V2 to V3
4. Conclusion

For a detailed overview of the differences for each NFT API endpoint in V2 and V3 check out NFT API V2 vs. V3 Endpoint Differences

Introduction

Welcome to the NFT API V2 to V3 Migration Guide! This guide has been designed to assist you in transitioning your projects from using the V2 version of our NFT API to the improved V3 version. Upgrading to NFT API V3 will bring numerous benefits, such as more consistent response formats, stricter typing, and overall enhanced ease of use. We believe that the improvements made in V3 will enable developers to work more efficiently and create more robust applications.

📘

NOTE

This guide specifically focuses on migrating projects that use direct API calls to interact with the NFT API.

The response formats and migration steps in this guide are not applicable to projects using the SDK. For SDK formats refer to Alchemy SDK Documentation. Currently, the SDK utilizes NFT API V2 and we have plans to migrate to V3 eventually.

Overview of Changes in NFT API V3

In response to user feedback, we've introduced several high-level changes in NFT API V3, which are outlined below:

1. Strict Types: In V3, all fields have a strict type (string, map, or integer), ensuring that you receive predictable and reliable data.

2. Mandatory fields: Fields that are null will always be available in the response. This differs from V2, where null fields were sometimes missing.

3. Consistent format across APIs: All APIs in V3 return a consistent format for every model. For example, the contract model in the NFT model and the contract model in the contract metadata will appear identical regardless of which API they are served on.

4. Flat response format: V3 responses aim to have a flat structure, making them easier to parse and consume.

5. Ease of consumption: We've designed V3 responses with ease of consumption in mind, helping you to more quickly understand and utilize the data.

6. Checksummed addresses: All addresses in V3 are checksummed addresses, whereas in V2, we served lowercased addresses. This change enhances the security and readability of addresses in the API.

7. Decimal String token IDs: All token IDs are now served as decimal strings. In V2, token IDs were sometimes served as hexadecimal or decimal strings, which could lead to confusion and potential errors.

The changes introduced in NFT API V3 are focused on providing a better, more consistent, and easier-to-use experience for developers. In the following sections, we will discuss the migration process and provide detailed mappings for each endpoint that has changed.

Migrating from V2 to V3

In this section, we'll provide steps to migrate your existing projects from NFT API V2 to V3. We will use a sample script that interacts with the getContractMetadata endpoint as an example to demonstrate the migration process. The steps are listed below.

Step 0: Analyzing The Existing Codebase

Before starting the migration, let's take a look at an existing node.js script using NFT API V2. This script retrieves contract metadata for a given contract address and prints the name, symbol, and OpenSea floor price. We will use this script as a basis for demonstrating the migration steps.

Existing V2 Script:

const axios = require('axios');
const apiKey = "demo" // Replace with your Alchemy API Key
const v2Url = `https://eth-mainnet.g.alchemy.com/nft/v2/${apiKey}/getContractMetadata`;

axios.get(v2Url, {
    params: {
        contractAddress: '0x8CC6517e45dB7a0803feF220D9b577326A12033f',
        refreshCache: true
    }
}).then(response => {
    const data = response.data;
    const contractMetadata = data.contractMetadata;
    const openSea = contractMetadata.openSea;

    console.log('Name:', contractMetadata.name);
    console.log('Symbol:', contractMetadata.symbol);
    console.log('OpenSea Floor Price:', openSea.floorPrice);
}).catch(error => {
    console.error(error);
});

Please note, to run the script given above you need to have a node.js project setup with axios installed so you can make requests to the NFT API. We are assuming you already have it all set up since you want to upgrade your existing project to V3. But if you don't, you can follow the steps given below:

1. Create a new node.js project by running the following commands in your terminal
   npmyarn

   mkdir alchemy-nft-api
   cd alchemy-nft-api
   npm init --yes
   

   mkdir alchemy-nft-api
   cd alchemy-nft-api
   yarn init --yes
   

2. Install the axioslibrary to be able to make requests to the NFT API
   npmyarn

   npm install axios
   

   yarn add axios
   

3. Create a new file called getContractMetadata.js and paste the script given above into it
   npmyarn

   touch getContractMetadata.js
   

   touch getContractMetadata.js
   

4. Run the script with the command given below
   npmyarn

   node getContractMetadata.js
   

   node getContractMetadata.js
   

5. You should see the output in your console
   bash

   Name: Link3
   Symbol: LINK3
   OpenSea Floor Price: 0.02
   

Step 1: Update Your API URL

Update the API URL by replacing the v2 segment with v3.

V3 URL:

const v3Url = `https://eth-mainnet.g.alchemy.com/nft/v3/${apiKey}/getContractMetadata`;

Step 2: Update Your Response Handling Code

Since the response structure has changed in V3, you will need to update your code to handle the new response format. Make sure to account for the changes in field names, data types, and structure as outlined in the Detailed Endpoint Mappings section.

For example, in the case of getContractMetadata endpoint's response, the contractMetadata object has been flattened, with its fields now directly accessible, and the openSea object has been renamed to openSeaMetadata. So we can update our existing script as follows:

Updated V3 Script:

const axios = require('axios');
const apiKey = "demo"; // Replace with your Alchemy API Key
const v3Url = `https://eth-mainnet.g.alchemy.com/nft/v3/${apiKey}/getContractMetadata`; // updated url

axios.get(v3Url, {
    params: {
        contractAddress: '0x8CC6517e45dB7a0803feF220D9b577326A12033f',
        refreshCache: true
    }
}).then(response => {
    const data = response.data;
    const openSeaMetadata = data.openSeaMetadata;

    console.log('Name:', data.name); // contract metadata fields like name and symbol are now directly accessible
    console.log('Symbol:', data.symbol);
    console.log('OpenSea Floor Price:', openSeaMetadata.floorPrice); // opensea object renamed to openseaMetadata
}).catch(error => {
    console.error(error);
});

Step 3: Testing The Updated Script

At this point, you have successfully migrated from NFT API V2 to V3, but before deploying the updated script to production, thoroughly test it to ensure it works as expected according to your application requirements. Verify that the output is correct and that there are no errors or unexpected behavior.

1. Run the updated script in your development environment. In this case, run it with the given command
   Shell

   node getContractMetadata.js
   

2. Compare the output to the output of the V2 script, making sure the data is consistent.

   Name: Link3
   Symbol: LINK3
   OpenSea Floor Price: 0.02
   

   In this case, as you can see, we are getting the same output as before so we are getting the desired result.
3. Perform additional tests, such as providing different parameters (in this case contract addresses), to ensure the script can handle various scenarios.
4. Verify that the script integrates correctly with other parts of your application, if applicable.

After successful testing, you can confidently deploy the updated script to production, taking advantage of the improvements in NFT API V3.

Conclusion

In this NFT API V2 to V3 Migration Guide, we've covered key changes and detailed the differences between V2 and V3. NFT API V3 offers numerous improvements, including consistent formatting, a flat response format, and ease of consumption. For a detailed look at the differences between V2 and V3 for each endpoint, check out NFT API V2 vs. V3 Endpoint Differences.

We strongly encourage developers to upgrade to NFT API V3 to benefit from these improvements and to ensure the best possible experience when working with NFTs.

By upgrading to NFT API V3, you'll be better equipped to build and maintain efficient applications, ensuring a seamless experience for your users. Happy coding!