πŸ₯‡Token Holders

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

πŸ₯‡ Token Holders

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

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

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

Table Of Contents

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

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:

React

npm install @airstack/airstack-react

Node

npm install @airstack/node

Then, add the following snippets to your code:

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

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 Lens Profile

Fetching

You can get all holders of an ERC20 token that has a Lens Profile:

Try Demo

Code

query MyQuery {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174" }
      }
      blockchain: polygon
      limit: 200
    }
  ) {
    TokenBalance {
      owner {
        socials(input: { filter: { dappName: { _eq: lens } } }) {
          profileName
          profileTokenId
          profileTokenIdHex
          userAssociatedAddresses
        }
      }
    }
  }
}

Formatting

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

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) ?? [];

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

[
  {
    "profileName": "lens/@humongosaur",
    "profileTokenId": "78804",
    "profileTokenIdHex": "0x0133d4",
    "userAssociatedAddresses": ["0x4c6e2223cea261d7ab48ff91fe1dff815df22c90"]
  }
  // ... other token holders
]

Get Holders of NFT That Has Lens Profile

Fetching

You can get all holders of NFT that has Lens Profile:

Try Demo

Code

query MyQuery {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0x9d90669665607f08005cae4a7098143f554c59ef" }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      owner {
        socials(input: { filter: { dappName: { _eq: lens } } }) {
          profileName
          profileTokenId
          profileTokenIdHex
          userAssociatedAddresses
        }
      }
    }
  }
}

Formatting

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

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) ?? [];

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

[
  {
    "profileName": "lens/@momoon",
    "profileTokenId": "16335",
    "profileTokenIdHex": "0x03fcf",
    "userAssociatedAddresses": ["0x6a48c3acbc91fb19931dfc1e4ab0753a1d17d0b5"]
  }
  // ... other token holders
]

Get Holders of POAP That Has Lens Profile

Fetching

You can get all holders of POAP that has Lens Profile:

Try Demo

Code

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

Formatting

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

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) ?? [];

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

[
  {
    "profileName": "lens/@0x131",
    "profileTokenId": "73916",
    "profileTokenIdHex": "0x0120bc",
    "userAssociatedAddresses": ["0x4455951fa43b17bd211e0e8ae64d22fb47946ade"]
  }
  // ... 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 Lens Profile:

Try Demo

Code

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

Formatting

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

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) ?? [];

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

[
  {
    "profileName": "lens/@okmax",
    "profileTokenId": "99154",
    "profileTokenIdHex": "0x018352",
    "userAssociatedAddresses": ["0x2ae074de12b20f853550a42ee1972746a6c3421e"]
  }
  // ... other token holders
]

Get Common Holders of 2 ERC20 Tokens That Have Lens Profile

Fetching

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

Try Demo

Code

query GetCommonHoldersOfApeCoinAndUSDC {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0x4d224452801aced8b2f0aebe155379bb5d594381" }
      }
      blockchain: ethereum
      limit: 200
    }
  ) {
    TokenBalance {
      owner {
        tokenBalances(
          input: {
            filter: {
              tokenAddress: {
                _eq: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
              }
            }
            limit: 200
          }
        ) {
          owner {
            socials(input: { filter: { dappName: { _eq: lens } } }) {
              profileName
              profileTokenId
              profileTokenIdHex
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

All the common holders' Lens profile 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:

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) ?? [];

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

[
  {
    "profileName": "lens/@0xkingelon",
    "profileTokenId": "25190",
    "profileTokenIdHex": "0x06266",
    "userAssociatedAddresses": ["0x64835b44c5a6947037172532fd2f60f8de4f2939"]
  }
  // ... other token holders
]

Get Common Holders of Two POAPs and That Has Lens Profile

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

Code

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: lens}}}) {
              profileName
              profileTokenId
              profileTokenIdHex
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

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

If user has any Lens profile, then socials will have non-null value and profileName will show the Lens profile name.

Formatting

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

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) ?? [];

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

[
  {
    "profileName": "lens/@schmidsi",
    "profileTokenId": "11129",
    "profileTokenIdHex": "0x02b79",
    "userAssociatedAddresses": ["0x546457bbddf5e09929399768ab5a9d588cb0334d"]
  }
  // ...other token holders
]

Get Common Holders of A Token (ERC20 or NFT) and A POAP That Has a Lens Profile

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

Code

query GetCommonHoldersOfNounsAndEthCC {
  TokenBalances(
    input: {filter: {tokenAddress: {_eq: "0x977e43ab3eb8c0aece1230ba187740342865ee78"}}, blockchain: ethereum, limit: 200}
  ) {
    TokenBalance {
      owner {
        poaps(input: {filter: {eventId: {_eq: "43882"}}}) {
          owner {
            socials(input: {filter: {dappName: {_eq: lens}}}) {
              profileName
              profileTokenId
              profileTokenIdHex
              userAssociatedAddresses
            }
          }
        }
      }
    }
  }
}

All the common holders' Lens profile 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:

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) ?? [];

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

[
  {
    "profileName": "lens/@westlakevillage",
    "profileTokenId": "99755",
    "profileTokenIdHex": "0x0185ab",
    "userAssociatedAddresses": ["0x8ec94086a724cbec4d37097b8792ce99cadcd520"]
  },
  {
    "profileName": "lens/@brad",
    "profileTokenId": "116598",
    "profileTokenIdHex": "0x01c776",
    "userAssociatedAddresses": ["0x8ec94086a724cbec4d37097b8792ce99cadcd520"]
  },
  {
    "profileName": "lens/@bradorbradley",
    "profileTokenId": "36",