Launch Explorer API Studio

⛓ī¸Holder Snapshots

Learn how to use Airstack to fetch token holders at a specific point in time.

Airstack provides easy-to-use Snapshots APIs for fetching token holders at a specific point in time. This feature set is currently available for the Ethereum, Base, Degen Chain, and other Airstack-supported chains blockchain.

The Snapshots API use timestamp, date, or block number as an input to specify the time:

NameTypeDescription

blockNumber

Int

Allows filtering based on specific block number (integer), 14562584

date

Date

Allows filtering based on specific date with YYYY-MM-DD format, e.g. 2023-10-25

timestamp

Int

Epoch Unix timestamp to fetch the specified time snapshots of balances/holders, e.g. 1702559139

and returns a list of tokens held by a user at the speficied timestamp, date, or block number.

Each object returned will be followed by a range of block number (startBlockNumber and endBlockNumber) and timestamp (startBlockTimestamp and endBlockTimestamp) that shows when was the token was first and last held:

NameTypeDescription

endBlockNumber

Int

Block number when the token was last held. If still hold to present, it will return -1.

endBlockTimestamp

Time

Timestamp when the token was last held. If still hold to present, it will return present timestamp.

startBlockNumber

Int

Block number when the token was first held by owner.

startBlockTimestamp

Time

Timestamp when the token was first held.

It is important to keep in mind that the startBlockNumber and startBlockTimestamp can have a different value to the input, but will always have time value less than or equal to the specified time.

For more details, check out the Snapshots API references.

It is important to note that AMM LP tokens or tokens that generate yield over time will not be reflected into the amount or formattedAmount field. Instead, it will only return the initial amount after staking/depositing.

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.

🤖 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 ERC20 Token Holders Snapshot On Ethereum at a Specified Time

You can fetch all the tokens holders of an ERC20 at a specified time on Ethereum by using Snapshots API and providing the ERC20 token address to tokenAddress input and time input to either date, timestamp or blockNumber:

Try Demo

Logohttps://app.airstack.xyz/query/RlfipZZEEK
Show me holder snapshots of ERC20 token USDC on Ethereum

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        date: { _eq: "2023-12-01" }
        tokenType: { _eq: ERC20 }
        tokenAddress: { _eq: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
      }
      blockchain: ethereum
    }
  ) {
    Snapshot {
      owner {
        addresses
        domains {
          name
          isPrimary
        }
        socials {
          profileName
          dappName
        }
        xmtp {
          isXMTPEnabled
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get NFT Collection Holders Snapshot on Ethereum at a Specified Time

You can fetch all the tokens holders of an NFT collection at a specified time on Ethereum by using Snapshots API and providing the NFT collection address to tokenAddress input and time input to either date, timestamp or blockNumber:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        date: { _eq: "2023-12-01" }
        tokenType: { _in: [ERC721, ERC1155] }
        tokenAddress: { _eq: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D" }
      }
      blockchain: ethereum
    }
  ) {
    Snapshot {
      owner {
        addresses
        domains {
          name
          isPrimary
        }
        socials {
          profileName
          dappName
        }
        xmtp {
          isXMTPEnabled
        }
      }
      tokenId
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
        metaData {
          name
          description
          attributes {
            value
            trait_type
            maxValue
            displayType
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get ERC20 Token Holders Snapshot On Base at a Specified Time

You can fetch all the tokens holders of an ERC20 at a specified time on Base by using Snapshots API and providing the ERC20 token address to tokenAddress input and time input to either date, timestamp or blockNumber:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        date: { _eq: "2023-12-01" }
        tokenType: { _eq: ERC20 }
        tokenAddress: { _eq: "0x4158734d47fc9692176b5085e0f52ee0da5d47f1" }
      }
      blockchain: base
    }
  ) {
    Snapshot {
      owner {
        addresses
        domains {
          name
          isPrimary
        }
        socials {
          profileName
          dappName
        }
        xmtp {
          isXMTPEnabled
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get NFT Collection Holders Snapshot on Base at a Specified Time

You can fetch all the tokens holders of an NFT collection at a specified time on Base by using Snapshots API and providing the NFT collection address to tokenAddress input and time input to either date, timestamp or blockNumber:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        date: { _eq: "2023-12-01" }
        tokenType: { _in: [ERC721, ERC1155] }
        tokenAddress: { _eq: "0xf0d0df7142f60f7f3847463a509fd8969e3e3a27" }
      }
      blockchain: base
    }
  ) {
    Snapshot {
      owner {
        addresses
        domains {
          name
          isPrimary
        }
        socials {
          profileName
          dappName
        }
        xmtp {
          isXMTPEnabled
        }
      }
      tokenId
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
        metaData {
          name
          description
          attributes {
            value
            trait_type
            maxValue
            displayType
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get ERC20 Token Holders Snapshot On Zora at a Specified Time

You can fetch all the tokens holders of an ERC20 at a specified time on Zora by using Snapshots API and providing the ERC20 token address to tokenAddress input and time input to either date, timestamp or blockNumber:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        date: { _eq: "2023-12-01" }
        tokenType: { _eq: ERC20 }
        tokenAddress: { _eq: "0xD838D5b87439e17B0194fd43e37300cD99Aa3DE0" }
      }
      blockchain: zora
    }
  ) {
    Snapshot {
      owner {
        addresses
        domains {
          name
          isPrimary
        }
        socials {
          profileName
          dappName
        }
        xmtp {
          isXMTPEnabled
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get NFT Collection Holders Snapshot on Zora at a Specified Time

You can fetch all the tokens holders of an NFT collection at a specified time on Zora by using Snapshots API and providing the NFT collection address to tokenAddress input and time input to either date, timestamp or blockNumber:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        date: { _eq: "2024-01-30" }
        tokenType: { _in: [ERC721, ERC1155] }
        tokenAddress: { _eq: "0xa15Bb830aCD9Ab46164e6840E3ef2dBBF9c5E2B3" }
      }
      blockchain: zora
    }
  ) {
    Snapshot {
      owner {
        addresses
        domains {
          name
          isPrimary
        }
        socials {
          profileName
          dappName
        }
        xmtp {
          isXMTPEnabled
        }
      }
      tokenId
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
        metaData {
          name
          description
          attributes {
            value
            trait_type
            maxValue
            displayType
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Developer Support

If you have any questions or need help regarding fetching holder snapshots data, please join our Airstack's Telegram group.

More Resources

PreviousBalance SnapshotsNextWallet

Last updated

Was this helpful?