How to Get NFT Owners at a Specific Block Height Using the GoldRush API

This guide walks you through how to get NFT owners/holders for a collection at a specific block height (time). This is useful for airdrops, token gating, etc!

Introduction

This guide demonstrates how to use the GoldRush API to retrieve NFT ownership data at specific block heights, a key capability for implementing airdrops, granting exclusive benefits, and enabling token gating. By leveraging the GoldRush SDK in TypeScript, you can enrich your applications, reward community loyalty, and ensure transparent and fair access to digital assets.

Why Retrieve NFT Owners Data at Specific Block Heights?

Retrieving a snapshot of NFT holders as of a certain block height is crucial for several use cases that directly benefit both creators and consumers in the blockchain ecosystem:

Airdrops: Projects can use historical data to determine eligibility for airdrops, ensuring that rewards or incentives are distributed to holders who owned the NFTs at a specific time, fostering loyalty and community engagement.
Exclusive Benefits: Access to events, content, or services can be granted based on NFT ownership at a certain block height. This practice is especially useful for offering perks to early adopters or long-term holders, enhancing the perceived value and exclusivity of owning NFTs.
Token Gating: By verifying ownership at particular block heights, projects can implement token gating to restrict access to certain areas of a platform or to special functionalities. This method is used to create tiered access within communities, where benefits increase based on the duration or timing of ownership.

These strategic applications not only enhance the utility and allure of NFTs but also empower developers and project owners to create more dynamic and engaged communities around their offerings.

Tutorial

1

Install the GoldRush SDK

Before diving into the code, ensure your development environment is set up by installing the GoldRush SDK:

npm install @covalenthq/client-sdk

yarn add @covalenthq/client-sdk

2

Initialize the Client

Import the necessary classes from the SDK and initialize your client with your API key:

Replace "YOUR_API_KEY" with your actual GoldRush API key, which you can obtain by signing up on their platform.

import { CovalentClient, Chains } from "@covalenthq/client-sdk";

const client = new CovalentClient("YOUR_API_KEY");

3

Fetching NFT Holders

To fetch NFT holders, use the getTokenHoldersV2ForTokenAddress method. You need to specify the blockchain chain, contract address, and the specific block height:

async function getNFTOwners(chain: Chains | string | number, contractAddress: string, blockHeight: number) {
    try {
        const response = await client.BalanceService.getTokenHoldersV2ForTokenAddress(chain, contractAddress, { blockHeight: blockHeight });
        if (!response.error) {
            console.log(response.data);
            return response.data;
        } else {
            console.log(response.error_message);
        }
    } catch (error) {
        console.error("An error occurred:", error);
    }
}

4

Example Usage

Here is an example of how to call the function using specific parameters:


const chain = Chains.ETH_MAINNET; // Ethereum Mainnet
const contractAddress = "0x..."; // The NFT contract address
const blockHeight = 1234567; // Block height of interest

getNFTOwners(chain, contractAddress, blockHeight);

Tips and Additional Resources

This service supports both ERC-20 or ERC-721 token standards. To returns historic token holders, set the block height to latest.

For more detailed information on using the GoldRush API, refer to the official documentation. You can also explore the SDK further on npm.

Conclusion

By leveraging the GoldRush SDK, as demonstrated in this guide, developers can efficiently integrate ownership-based features into their applications, thus enriching the ecosystem and adding tangible value to the NFT holders. Whether you're aiming to boost participation in your project or provide exclusive content, historical data retrieval plays a pivotal role in creating a vibrant and dynamic community.

How to Create Fractional NFTs: a Step-By-Step Guide

How to Implement a Rental NFT Contract