Launch Explorer API Studio

📸Balance Snapshots

Learn how to use the Airstack API fetch token balances time-series data of user(s) and their variations on Base.

Airstack provides easy-to-use Snapshots APIs for fetching token balances at a specific point in time. This feature set is currently available for the Ethereum, Base, Zora, and Gold.

Degen Chain L3 support for Snapshots API coming soon.

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 User's Token Balances Of Specified Time on Ethereum

You can fetch all the tokens ever held by user at a specified time on Ethereum by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and time input to either date, timestamp or blockNumber:

Try Demo

Logohttps://app.airstack.xyz/query/6mXI6CHjL8
Show me balance snapshots of users on Ethereum on Aug 18, 2023

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        date: {_eq: "2023-08-18"} # Specifying date to Aug 18, 2023
      },
      blockchain: ethereum,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get User's Token Balances Of Specified Time on Base

You can fetch all the tokens ever held by user at a specified time on Base by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and time input to either date, timestamp or blockNumber:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        date: {_eq: "2023-08-18"} # Specifying date to Aug 18, 2023
      },
      blockchain: base,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get User's Token Balances Of Specified Time on Ethereum and Base

You can fetch all the tokens ever held by user at a specified time across multiple chains, e.g. Ethereum and Base, by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and time input to either date, timestamp or blockNumber:

Try Demo

Logohttps://app.airstack.xyz/query/Et9sxm16nq
Show me balance snapshots of users on Base on Aug 18, 2023

Code

query MyQuery {
  Ethereum: Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        date: {_eq: "2023-08-18"} # Specifying date to Aug 18, 2023
      },
      blockchain: ethereum,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
  Base: Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        date: {_eq: "2023-08-18"} # Specifying date to Aug 18, 2023
      },
      blockchain: base,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get User's Historical Balances Of Specified ERC20 Token

You can fetch user's historical token balances of a specified ERC20 token and their time series data by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and specifying tokenAddress with the ERC20 token address:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        # Optional – specify type to ERC20
        tokenType: {_in: [ERC20]},
        # specify ERC20 token addresss
        tokenAddress: {_eq: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}
      },
      blockchain: base,
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get User's Historical Balance Of Specified NFT Collection

You can fetch user's historical token balances of a specified NFT collection and their time series data by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and specifying tokenAddress with the ERC721/1155 NFT collection address:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        # Optional – specify type to only ERC721/1155
        tokenType: {_in: [ERC721, ERC1155]},
        # Specify NFT contract address
        tokenAddress: {_eq: "0x344bd884B47dfc988F7e47851d576E0AC083A16F"}
      },
    blockchain: base,
    limit: 200
  }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      formattedAmount
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get User's Historical Balance Of Specified NFT

You can fetch user's historical token balances of a specified ERC721/1155 NFT and their time series data by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and specifying tokenAddress with the ERC721 NFT token address and tokenId with the corresponding token ID:

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "vitalik.eth",
            "lens/@vitalik",
            "fc_fname:vitalik"
          ]
        },
        # Optional – specify type ERC721/1155
        tokenType: {_in: [ERC721, ERC1155]},
        # specify NFT token address & ID
        tokenAddress: {_eq: "0x344bd884B47dfc988F7e47851d576E0AC083A16F"}
        tokenId: {_eq: "1001"}
      },
    blockchain: base,
    limit: 200
  }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      formattedAmount
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Get User's Historical Balance Of Certain Token Type(s)

You can fetch user's historical token balances of specified token type(s), that is ERC20/721/1155, and their time series data by using Snapshots API and providing user(s) 0x address, ENS, cb.id, Lens, or Farcaster to owner input and specifying tokenType with the token type (ERC20/721/1155):

Try Demo

Code

query MyQuery {
  Snapshots(
    input: {
      filter: {
        owner: {
          _in: [
            "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            "vitalik.eth"
            "lens/@vitalik"
            "fc_fname:vitalik"
          ]
        }
        tokenType: { _in: [ERC20] }
      }
      blockchain: base
      limit: 200
    }
  ) {
    Snapshot {
      tokenAddress
      tokenId
      tokenType
      token {
        name
        symbol
        isSpam
      }
      tokenNft {
        contentValue {
          image {
            extraSmall
            large
            medium
            original
            small
          }
        }
      }
      startBlockNumber
      startBlockTimestamp
      endBlockNumber
      endBlockTimestamp
    }
    pageInfo {
      hasNextPage
      hasPrevPage
      nextCursor
      prevCursor
    }
  }
}

Developer Support

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

More Resources

PreviousPOAPsNextHolder Snapshots

Last updated

Was this helpful?