🥇Token Holders

Learn how to get all Farcaster users who own a specific token, NFT, or POAP, or a min amount of that token. Get combinations of NFTs or POAPs + Farcaster, e.g. Has POAP1 and POAP2 and has Farcaster

🥇 Token Holders

Airstack provides easy-to-use APIs for enriching Farcaster applications and integrating on-chain and off-chain data with Farcaster.

In this tutorial, you will learn how to fetch all Farcaster users who own a specific ERC20 token, NFT (ERC721 and ERC1155), or POAPs.

In addition, you will also learn how to fetch common Farcaster users that hold two different assets at the same time, e.g. Farcaster users that hold both EthLisbon and EthCC[6] POAP.

Table Of Contents

In this guide you will learn how to use Airstack to:

• Get Holders of an ERC20 Token That Has Farcaster

• Get Holders of NFT That Has Farcaster

• Get Holders of POAP That Has Farcaster

• Get Holders That Held Specific Amount of ERC20 Token

• Get Common Holders of 2 ERC20 Tokens That Has Farcaster

• Get Common Holders of Two POAPs That Has Farcaster

• Get Common Holders of A Token (ERC20 or NFT) and A POAP That Has Farcaster

Pre-requisites

• An Airstack account

• Basic knowledge of GraphQL

Get Started

JavaScript/TypeScript/Python

If you are using JavaScript/TypeScript or Python, Install the Airstack SDK:

npm

React

npm install @airstack/airstack-react

Node

npm install @airstack/node

yarn

React

yarn add @airstack/airstack-react

Node

yarn add @airstack/node

pnpm

React

pnpm install @airstack/airstack-react

Node

pnpm install @airstack/node

pip

pip install airstack

Then, add the following snippets to your code:

React

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>;
  }
};

Node

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);

Python

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.

Get Holders of an ERC20 Token That Has Farcaster

Fetching

You can get all holders of an ERC20 token that has Farcaster:

Try Demo

https://app.airstack.xyz/query/dErT36be21

Show all token holders of USD Coin on Ethereum that has Farcaster

Code

Query

query MyQuery {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174" }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      owner {
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "owner": {
            "socials": [
              {
                "profileName": "vbuterin",
                "userId": "5650",
                "userAssociatedAddresses": [
                  "0xadd746be46ff36f10c81d6e3ba282537f4c68077",
                  "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.TokenBalances?.TokenBalance?.map(({ owner }) =>
    owner?.socials?.length > 0 ? owner?.socials : null
  )
    .filter(Boolean)
    .flat(2)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

Python

def format_function(data):
    result = []
    if data and 'TokenBalances' in data and 'TokenBalance' in data['TokenBalances']:
        for item in data['TokenBalances']['TokenBalance']:
            if 'owner' in item and 'socials' in item['owner'] and item['owner']['socials'] is not None:
                result.append(item['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "vbuterin",
    "userId": "5650",
    "userAssociatedAddresses": [
      "0xadd746be46ff36f10c81d6e3ba282537f4c68077",
      "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
    ]
  }
  // ... other token holders
]

Get Holders of NFT That Has Farcaster

Fetching

You can get all holders of NFT that has Farcaster:

Try Demo

https://app.airstack.xyz/query/Qyl0sm2u8E

Show all token holders of BoredApeYachtClub that has Farcaster

Code

Query

query MyQuery {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      owner {
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "owner": {
            "socials": [
              {
                "profileName": "durtis",
                "userId": "11926",
                "userAssociatedAddresses": [
                  "0xcb0b3404b7d5db8622511427c09a1bba450d3c0f",
                  "0xe5ca890a0ef2f128eb3267e4711c6bf3306ec024"
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.TokenBalances?.TokenBalance?.map(({ owner }) =>
    owner?.socials?.length > 0 ? owner?.socials : null
  )
    .filter(Boolean)
    .flat(2)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

Python

def format_function(data):
    result = []
    if data and 'TokenBalances' in data and 'TokenBalance' in data['TokenBalances']:
        for item in data['TokenBalances']['TokenBalance']:
            if 'owner' in item and 'socials' in item['owner'] and item['owner']['socials'] is not None:
                result.append(item['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "durtis",
    "userId": "11926",
    "userAssociatedAddresses": [
      "0xcb0b3404b7d5db8622511427c09a1bba450d3c0f",
      "0xe5ca890a0ef2f128eb3267e4711c6bf3306ec024"
    ]
  }
  // ... other token holders
]

Get Holders of POAP That Has Farcaster

Fetching

You can get all holders of POAP that has Farcaster:

Try Demo

https://app.airstack.xyz/query/BsPwpo9zYu

Show all POAP holders of EthCC[6] - Attendee that has Farcaster

Code

Query

query MyQuery {
  Poaps(
    input: {
      filter: { eventId: { _eq: "141910" } }
      blockchain: ALL
      limit: 50
    }
  ) {
    Poap {
      owner {
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
    }
  }
}

Response

{
  "data": {
    "Poaps": {
      "Poap": [
        {
          "owner": {
            "socials": [
              {
                "profileName": "megankaspar",
                "userId": "7361",
                "userAssociatedAddresses": [
                  "0xadf37a0d500c748edb1c689a1be26472e583dcb5",
                  "0x4455951fa43b17bd211e0e8ae64d22fb47946ade",
                  "0xfaedb341b0faced023099d7b0ccd23c2ec5ed7a5"
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.Poaps?.Poap?.map(({ owner }) =>
    owner?.socials?.length > 0 ? owner?.socials : null
  )
    .filter(Boolean)
    .flat(2)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

Python

def format_function(data):
    result = []
    if data and 'Poaps' in data and 'Poap' in data['Poaps']:
        for item in data['Poaps']['Poap']:
            if 'owner' in item and 'socials' in item['owner'] and item['owner']['socials'] is not None:
                result.append(item['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "megankaspar",
    "userId": "7361",
    "userAssociatedAddresses": [
      "0xadf37a0d500c748edb1c689a1be26472e583dcb5",
      "0x4455951fa43b17bd211e0e8ae64d22fb47946ade",
      "0xfaedb341b0faced023099d7b0ccd23c2ec5ed7a5"
    ]
  }
  // ... other token holders
]

Get Holders That Held Specific Amount of ERC20 Token

Fetching

You can get all holders of an ERC20 token that have a minimum amount held in their balances which also have Farcaster:

Try Demo

https://app.airstack.xyz/query/c1yxMwkl5B

Show all user that has at least 10 USD Coin with their Farcaster

Code

Query

query MyQuery {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }
        formattedAmount: { _gte: 10 }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      owner {
        identity
        socials(input: { filter: { dappName: { _eq: farcaster } } }) {
          profileName
          userId
          userAssociatedAddresses
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "owner": {
            "identity": "0xfc84d2742d0f1a66d76d51a2980f48a770a9456e",
            "socials": [
              {
                "profileName": "yusuf",
                "userId": "1081",
                "userAssociatedAddresses": [
                  "0x3da8748ca04694d8f889fe457db96c2e7e7f381b",
                  "0xfc84d2742d0f1a66d76d51a2980f48a770a9456e",
                  "0x302882ea764225633c74838d702bb591774955a3"
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.TokenBalances?.TokenBalance?.map(({ owner }) =>
    owner?.socials?.length > 0 ? owner?.socials : null
  )
    .filter(Boolean)
    .flat(2)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

Python

def format_function(data):
    result = []
    if data and 'TokenBalances' in data and 'TokenBalance' in data['TokenBalances']:
        for item in data['TokenBalances']['TokenBalance']:
            if 'owner' in item and 'socials' in item['owner'] and item['owner']['socials'] is not None:
                result.append(item['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "durtis",
    "userId": "11926",
    "userAssociatedAddresses": [
      "0xcb0b3404b7d5db8622511427c09a1bba450d3c0f",
      "0xe5ca890a0ef2f128eb3267e4711c6bf3306ec024"
    ]
  }
  // ... other token holders
]

Get Common Holders of 2 ERC20 Tokens That Has Farcaster

Fetching

You can fetch the common holders of two given ERC20, e.g. USDT and USDC:

Try Demo

https://app.airstack.xyz/query/f9pU5NDyEe

Get Common Holders of 2 ERC20 Tokens That Has Farcaster

Code

Query

query GetCommonHoldersOfUSDTAndUSDC {
  TokenBalances(input: {filter: {tokenAddress: {_eq: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}}, blockchain: ethereum, limit: 200}) {
    TokenBalance {
      owner {
        tokenBalances(input: {filter: {tokenAddress: {_eq: "0xdAC17F958D2ee523a2206206994597C13D831ec7"}}, limit: 200}) {
          owner {
            socials(input: {filter: {dappName: {_eq: farcaster}}}) {
              profileName
              userId
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "owner": {
            "tokenBalances": [
              {
                "owner": {
                  "socials": [
                    {
                      "profileName": "vbuterin",
                      "userId": "5606",
                      "userAssociatedAddresses": [
                        "0xadd746be46ff36f10c81d6e3ba282537f4c68077",
                        "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
                      ]
                    }
                  ]
                }
              }
            ]
          }
        },
        {
          "owner": {
            "tokenBalances": [] // Have USDT, but no USDC
          }
        }
      ]
    }
  }
}

All the common holders' Farcaster details will be returned inside the innermost owner.socials field.

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.TokenBalances?.TokenBalance?.map(({ owner }) =>
    owner?.tokenBalances?.map(({ owner }) =>
      owner?.socials?.length > 0 ? owner?.socials : null
    )
  )
    .filter(Boolean)
    .flat(2)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

Python

def format_function(data):
    result = []
    if data and 'TokenBalances' in data and 'TokenBalance' in data['TokenBalances']:
        for item in data['TokenBalances']['TokenBalance']:
            if 'owner' in item and 'tokenBalances' in item['owner']:
                for token_balance in item['owner']['tokenBalances']:
                    if 'owner' in token_balance and 'socials' in token_balance['owner'] and len(token_balance['owner']['socials']) > 0:
                        result.append(token_balance['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "vbuterin",
    "userId": "5606",
    "userAssociatedAddresses": [
      "0xadd746be46ff36f10c81d6e3ba282537f4c68077",
      "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
    ]
  }
  // ... other token holders
]

Get Common Holders of Two POAPs and That Has Farcaster

Fetching

You can fetch the common holders of two given POAP event IDs, e.g. EthGlobal Lisbon 2023 Partner Attendee POAP & EthCC[6] Attendee POAP:

Try Demo

https://app.airstack.xyz/query/tjIzrCbvsd

Get Common Holders Of EthGlobal Lisbon and EthCC POAPs

Code

Query

query GetCommonHoldersOfEthGlobalLisbonAndEthCC {
  Poaps(input: {filter: {eventId: {_eq: "127462"}}, blockchain: ALL, limit: 200}) {
    Poap {
      owner {
        poaps(input: {blockchain: ALL, filter: {eventId: {_eq: "141910"}}}) {
          owner {
            socials(input: {filter: {dappName: {_eq: farcaster}}}) {
              profileName
              userId
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "Poaps": {
      "Poap": [
        {
          "owner": {
            "poaps": [
              {
                "owner": {
                  "socials": [
                    {
                      "profileName": "vbuterin",
                      "userId": "5606",
                      "userAssociatedAddresses": [
                        "0xadd746be46ff36f10c81d6e3ba282537f4c68077",
                        "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
                      ]
                    }
                  ]
                }
              }
            ]
          }
        },
        {
          "owner": {
            "poaps": null // Have EthGlobal Lisbon, but no EthCC[6]
          }
        }
      ]
    }
  }
}

All the common holders' Farcaster details will be returned inside the innermost owner.socials field.

If user has any Farcaster, then socials will have non-null value and profileName and userId will show both the Farcaster name and ID, respectively.

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.Poaps?.Poap?.map(({ owner }) =>
    owner?.poaps?.map(({ owner }) =>
      owner?.socials?.length > 0 ? owner?.socials : null
    )
  )
    .filter(Boolean)
    .flat(2)
    .filter((address, index, array) => array.indexOf(address) === index) ?? [];

Python

def format_function(data):
    result = []

    if data and 'Poaps' in data and 'Poap' in data['Poaps']:
        for poap in data['Poaps']['Poap']:
            if 'owner' in poap and 'poaps' in poap['owner'] and poap['owner']['poaps'] is not None:
                for owner_poap in poap['owner']['poaps']:
                    if 'owner' in owner_poap and 'socials' in owner_poap['owner'] and owner_poap['owner']['socials'] is not None:
                        result.append(owner_poap['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "schmidsi",
    "userId": "14088",
    "userAssociatedAddresses": [
      "0xcc8fd0d88abf88d006fea4487e59e2b39f281095",
      "0x546457bbddf5e09929399768ab5a9d588cb0334d"
    ]
  }
  // ...other token holders
]

Get Common Holders of A Token (ERC20 or NFT) and A POAP That Has Farcaster

Fetching

You can fetch the common holder of a token and a POAP by providing the token contract address and the POAP event ID:

Try Demo

https://app.airstack.xyz/query/8xD3r6s6lU

Show common holders of Nouns NFT and EthCC POAP that also have Farcaster

Code

Query

query GetCommonHoldersOfNounsAndEthCC {
  TokenBalances(
    input: {filter: {tokenAddress: {_eq: "0x9c8ff314c9bc7f6e59a9d9225fb22946427edc03"}}, blockchain: ethereum, limit: 200}
  ) {
    TokenBalance {
      owner {
        poaps(input: {filter: {eventId: {_eq: "141910"}}}) {
          owner {
            socials(input: {filter: {dappName: {_eq: farcaster}}}) {
              profileName
              userId
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "owner": {
            "poaps": [
              {
                "owner": {
                  "socials": [
                    {
                      "profileName": "worthalter",
                      "userId": "9456",
                      "userAssociatedAddresses": [
                        "0xc19628f57a46389b0ac0fc113de273f91b07faca",
                        "0xf6b6f07862a02c85628b3a9688beae07fea9c863"
                      ]
                    }
                  ]
                }
              }
            ]
          }
        },
        {
          "owner": {
            "poaps": null // Have Nouns, but no EthCC[6] POAP
          }
        }
      ]
    }
  }
}

All the common holders' Farcaster details will be returned inside the innermost owner.socials field.

Formatting

To get the list of all holders in a flat array, use the following format function:

JavaScript

const formatFunction = (data) =>
  data?.TokenBalances?.TokenBalance?.map(({ owner }) =>
    owner?.poaps?.map(({ owner }) => owner?.socials)
  )
    .filter(Boolean)
    .flat(2)
    .filter((social, index, array) => array.indexOf(social) === index) ?? [];

Python

def format_function(data):
    result = []
    if data is not None and 'TokenBalances' in data and 'TokenBalance' in data['TokenBalances']:
        for item in data['TokenBalances']['TokenBalance']:
            if 'owner' in item and 'poaps' in item['owner'] and item['owner']['poaps'] is not None:
                for poap in item['owner']['poaps']:
                    if 'owner' in poap and 'socials' in poap['owner'] and poap['owner']['socials'] is not None:
                        result.append(poap['owner']['socials'])

    result = [item for sublist in result for item in sublist]

    return result

The final result will the the list of all common holders in an array:

[
  {
    "profileName": "worthalter",
    "userId": "9456",
    "userAssociatedAddresses": [
      "0xc19628f57a46389b0ac0fc113de273f91b07faca",
      "0xf6b6f07862a02c85628b3a9688beae07fea9c863"
    ]
  }
  // ...other token holders
]

Developer Support

If you have any questions or need help regarding fetching holders or attendees of multiple POAPs, please join our Airstack's Telegram group.

More Resources

• Combinations

  • Multiple ERC20s or NFTs

  • Mutliple POAPs

  • Combinations of ERC20s, NFTs, and POAPs

  • Social Combinations

• TokenBalances API Reference

• POAPs API Reference