đī¸ NFT HoldersLearn how to fetch NFT holders of a specific NFT and NFT collection(s) and how to use the same query to check whether a given user holds a specific NFT collection.
Airstack provides easy-to-use NFT APIs for enriching Web3 applications with onchain and offchain NFT data from Ethereum, Base, Degen Chain, and other Airstack-supported chains .
Table Of Contents
In this guide you will learn how to use Airstack to:
Pre-requisites
Basic knowledge of GraphQL
Get Started
JavaScript/TypeScript/Python
If you are using JavaScript/TypeScript or Python, Install the Airstack SDK:
npm yarn pnpm pip
React
Copy npm install @airstack/airstack-react
Node
Copy npm install @airstack/node
React
Copy yarn add @airstack/airstack-react
Node
Copy yarn add @airstack/node
React
Copy pnpm install @airstack/airstack-react
Node
Copy pnpm install @airstack/node
Then, add the following snippets to your code:
React Node Python
Copy import { init , useQuery } from "@airstack/airstack-react" ;
init ( "YOUR_AIRSTACK_API_KEY" );
const query = `YOUR_QUERY` ; // Replace with GraphQL Query
const Component = () => {
const { data , loading , error } = useQuery (query);
if (data) {
return < p >Data: { JSON .stringify (data)}</ p >;
}
if (loading) {
return < p >Loading...</ p >;
}
if (error) {
return < p >Error: { error .message}</ p >;
}
};
Copy import { init , fetchQuery } from "@airstack/node" ;
init ( "YOUR_AIRSTACK_API_KEY" );
const query = `YOUR_QUERY` ; // Replace with GraphQL Query
const { data , error } = await fetchQuery (query);
console .log ( "data:" , data);
console .log ( "error:" , error);
Copy import asyncio
from airstack . execute_query import AirstackClient
api_client = AirstackClient (api_key = "YOUR_AIRSTACK_API_KEY" )
query = """YOUR_QUERY""" # Replace with GraphQL Query
async def main ():
execute_query_client = api_client . create_execute_query_object (
query = query)
query_response = await execute_query_client . execute_query ()
print (query_response.data)
asyncio . run ( main ())
Other Programming Languages
To access the Airstack APIs in other languages, you can use https://api.airstack.xyz/gql as your GraphQL endpoint.
đ¤ AI Natural Language â Airstack provides an AI solution for you to build GraphQL queries to fulfill your use case easily. You can find the AI prompt of each query in the demo's caption or title for yourself to try.
Get NFT Holder(s) of A Specific NFT
You can use Airstack to fetch NFT holder(s) of a specifc NFT by using the TokenBalances
API and providing the NFT collection address(es) to tokenAddress
and the token ID to tokenId
as an input:
For ERC721 NFT, there's only 1 unique holder for each token ID.
For ERC1155 NFT, there can be multiple holders for a token ID.
Try Demo
Code
Query Response
Copy query MyQuery {
TokenBalances(
input: {
filter : {
tokenAddress : { _eq : "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" }
tokenId : { _eq : "6891" }
}
blockchain : ethereum
}
) {
TokenBalance {
owner {
addresses
domains {
name
isPrimary
}
socials {
dappName
profileName
userAssociatedAddresses
}
xmtp {
isXMTPEnabled
}
}
}
}
}
Copy {
"data" : {
"TokenBalances" : {
"TokenBalance" : [
{
"owner" : {
"addresses" : [ "0x9831bb48e27a6b74260823c10d15b577e891a37b" ] ,
"domains" : [
{
"name" : "dhtong.eth" ,
"isPrimary" : false
}
] ,
"socials" : [
{
"dappName" : "farcaster" ,
"profileName" : "dht" ,
"userAssociatedAddresses" : [
"0x6e2946ec7cc8b9473749319ace351c5e33f04960" ,
"0x9831bb48e27a6b74260823c10d15b577e891a37b"
]
}
] ,
"xmtp" : [
{
"isXMTPEnabled" : true
}
]
}
}
] ,
"pageInfo" : {
"nextCursor" : "" ,
"prevCursor" : ""
}
}
}
}
Get NFT Holders of NFT Collection(s)
You can use Airstack to fetch NFT holders of a given NFT collection(s) by using the TokenBalances
API and providing the NFT collection address(es) to tokenAddress
input:
Try Demo
Code
Query Response
Copy query MyQuery {
TokenBalances(
input: {
filter : {
tokenAddress : { _in : [ "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" ] }
}
blockchain : ethereum
limit : 50
}
) {
TokenBalance {
tokenId
owner {
addresses
domains {
name
isPrimary
}
socials {
dappName
profileName
userAssociatedAddresses
}
xmtp {
isXMTPEnabled
}
}
}
pageInfo {
nextCursor
prevCursor
}
}
}
Copy {
"data" : {
"TokenBalances" : {
"TokenBalance" : [
{
"tokenId" : "6891" ,
"owner" : {
"addresses" : [
"0x9831bb48e27a6b74260823c10d15b577e891a37b"
] ,
"domains" : [
{
"name" : "dhtong.eth" ,
"isPrimary" : false
}
] ,
"socials" : [
{
"dappName" : "farcaster" ,
"profileName" : "dht" ,
"userAssociatedAddresses" : [
"0x6e2946ec7cc8b9473749319ace351c5e33f04960" ,
"0x9831bb48e27a6b74260823c10d15b577e891a37b"
]
}
] ,
"xmtp" : [
{
"isXMTPEnabled" : true
}
]
}
} ,
] ,
"pageInfo" : {
"nextCursor": "eyJMYXN0VmFsdWVzTWFwIjp7Il9pZCI6eyJWYWx1ZSI6IjEweGJjNGNhMGVkYTc2NDdhOGFiN2MyMDYxYzJlMTE4YTE4YTkzNmYxM2QweGFhYTJkYTI1NWRmOWVlNzRjNzA3NWJjYjZkODFmOTc5NDA5MDhhNWQxNTYiLCJEYXRhVHlwZSI6InN0cmluZyJ9LCJsYXN0VXBkYXRlZFRpbWVzdGFtcCI6eyJWYWx1ZSI6IjE3MDA0MTA5MTkiLCJEYXRhVHlwZSI6IkRhdGVUaW1lIn19LCJQYWdpbmF0aW9uRGlyZWN0aW9uIjoiTkVYVCJ9",
"prevCursor" : ""
}
}
}
]
Check If User Hold A Specific NFT Collection
You can use Airstack to check if a user hold a given NFT Collection by using the TokenBalances
API.
For inputs, provide the NFT collection address(es) to tokenAddress
and user's 0x address, ENS domain, cb.id, Lens profile, or Farcaster fname/fid to owner
as an input:
Try Demo
Code
Query Response
Copy query MyQuery {
TokenBalances(
input: {
filter : {
tokenAddress : { _eq : "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" }
owner : { _eq : "0x9831bb48e27a6b74260823c10d15b577e891a37b" }
}
blockchain : ethereum
}
) {
TokenBalance {
owner {
addresses
domains {
name
isPrimary
}
socials {
dappName
profileName
userAssociatedAddresses
}
xmtp {
isXMTPEnabled
}
}
}
}
}
Copy {
"data" : {
"TokenBalances" : {
"TokenBalance" : [
{
"owner" : {
"addresses" : [ "0x9831bb48e27a6b74260823c10d15b577e891a37b" ] ,
"domains" : [
{
"name" : "dhtong.eth" ,
"isPrimary" : false
}
] ,
"socials" : [
{
"dappName" : "farcaster" ,
"profileName" : "dht" ,
"userAssociatedAddresses" : [
"0x6e2946ec7cc8b9473749319ace351c5e33f04960" ,
"0x9831bb48e27a6b74260823c10d15b577e891a37b"
]
}
] ,
"xmtp" : [
{
"isXMTPEnabled" : true
}
]
}
}
] ,
"pageInfo" : {
"nextCursor" : "" ,
"prevCursor" : ""
}
}
}
}
If the given user hold the specified NFT collection, then TokenBalances
will have non-null value as a response. Otherwise, the API will return null.
Developer Support
If you have any questions or need help regarding fetching NFT holders data, please join our Airstack's Telegram group.
More Resources