Solscan Historical Balance Snapshots: Building Retroactive NFT Airdrop Eligibility Lists

An NFT project launching a retroactive airdrop faces a straightforward but operationally complex problem: determining which wallet addresses held specific tokens or NFTs at a defined historical moment. The project cannot simply snapshot current holdings, because those reflect weeks or months of subsequent trading, transfers, and sales. The correct approach requires accessing the blockchain state as it existed on a precise block height or timestamp, then verifying which addresses met the eligibility criteria at that exact point in time.

This verification process is not theoretical. A project distributing governance tokens to holders of a previous NFT collection must prove which addresses held those NFTs when the eligibility window closed. Attempting to reconstruct this from memory, spreadsheets, or exchange records produces inconsistency and disputes. A proper airdrop foundation requires authoritative, transparent, and auditable historical data pulled directly from the blockchain. Solana’s public ledger contains this information, but accessing it efficiently and accurately demands the right tools.

Why retroactive snapshots matter more than current balances

The difference between a current balance and a historical snapshot determines fairness and legitimacy. A user who purchased an eligible NFT two days before the airdrop eligibility cutoff but sold it one day after should be included in the distribution. Another user who bought the same NFT in the open market months after the cutoff should not receive tokens, even if they still hold the NFT today. This distinction cannot be made by reading wallet balances in real time. It requires examining the state of the blockchain at a specific block height that corresponds to the announced eligibility moment.

Solana’s architecture makes this feasible because every transaction is recorded with a block number and timestamp. When an airdrop program specifies «all wallets holding token X as of block 215,000,000,» the requirement is precise and verifiable. A wallet explorer that can access historical data can display what a given address held at that block, not just what it holds now. Without this capability, an airdrop team must either accept the risk of including ineligible addresses or manually verify thousands of transaction histories—a process that scales poorly and introduces human error.

The stakes extend beyond fairness. A poorly constructed eligibility list can damage community trust. If token holders perceive that distribution was arbitrary, that ineligible addresses received tokens, or that eligible holders were excluded, the project’s reputation suffers. Conversely, publishing the methodology and allowing holders to verify their own eligibility on a public explorer creates transparency. Each address can see exactly why it was included or excluded, and anyone can audit the process by checking the same historical data.

Projects also face practical questions about timing. Should eligibility be determined at a past block height (for example, block 210,000,000, which occurred three months ago), or at a date announced in advance (for example, June 15 at 14:00 UTC)? Block heights are unambiguous and resist manipulation; dates require converting to the corresponding block height, which can introduce confusion if the conversion is done incorrectly. Many projects settle on both: announcing a date and publishing the exact block height that represents that moment.

Using Solscan to access and verify historical holdings

Solscan serves as the official blockchain explorer for Solana and provides the primary interface for retrieving historical balance data. The platform’s design centers on transparency and accessibility: no login is required, private keys are never requested, and all data is read-only. This open architecture means any airdrop team or community member can independently verify holdings at a specific block height without trusting a third party or exposing sensitive information.

The core workflow begins by identifying the target token or NFT collection. On Solscan.io, users can search for a token mint address or NFT collection address directly. Once located, the page displays the token’s current supply, holders, and transfers. However, for retroactive eligibility, the airdrop team needs to determine holdings at a historical moment. Solscan’s advanced search and API capabilities allow querying the state of token accounts at a specified block height, rather than the current state.

For each wallet address in question, the explorer displays the complete transaction history—every send, receive, and trade involving that address. By examining this history relative to the eligibility cutoff block, an airdrop team can determine when a user acquired the token and when they sold or transferred it away. If the transaction sequence shows that an address held the token at the cutoff block and no sales or transfers occurred between acquisition and that block, the address qualifies. If the address sold the token before the cutoff or acquired it after, it does not.

The transparency of this process is crucial. Unlike a centralized exchange, which might maintain private records of user balances, the Solana blockchain publicly records every token transfer. An airdrop team can publish the block height cutoff, provide a list of eligible addresses, and allow anyone to verify the list by looking up each address on Solscan and checking their holdings at that block. This public verifiability is what makes retroactive airdrops on-chain credible.

Building the eligibility snapshot from token holder data

The technical process of constructing an eligibility list requires gathering data about all addresses that held a target token or NFT collection at the specified block height. Solscan’s token holders feature displays all current addresses holding a token, along with their balances. However, for a retroactive snapshot, the team needs historical holder data—specifically, the set of addresses holding the token at block X, not block Y (where Y is the current height).

This is where Solscan’s API and data export capabilities become essential. The explorer provides programmatic access to historical account state, transaction records, and token balances at specified block heights. An airdrop team can use these APIs to query which addresses held balances in a particular token mint at the target block height, retrieve the balance amounts, and compile a list. This list becomes the source of truth for eligibility. If the cutoff was set at block 215,000,000 and the query returns 15,000 addresses holding at least 1 unit of the token at that height, those 15,000 addresses are eligible to receive the airdrop.

The challenge arises when dealing with NFTs, because NFTs are single-unit tokens (each with a supply of 1) and reside in individual accounts. An NFT collection is not a single token but a set of related tokens sharing a common creator or metadata standard. Determining all addresses that held any NFT from a collection requires querying all NFT mint addresses in that collection and checking which addresses held them at the target block. Solscan’s NFT analytics tools index collections and can identify all mints within a collection, but the airdrop team still needs to iterate through each mint and check historical holdings.

This multi-step process is where errors commonly occur. A team might accidentally query the current state instead of the historical state, leading to a list that excludes users who held the NFT at the cutoff but sold it since. They might miscalculate the block height corresponding to a date, shifting the eligibility window by hundreds of blocks. They might fail to exclude certain contract accounts or wrapped token representations, inflating the holder count. Solscan’s transparent data and public APIs allow teams to test their process iteratively and allow community members to audit and catch mistakes before tokens are distributed.

Handling edge cases and contested eligibility claims

In practice, retroactive airdrops inevitably encounter edge cases. A user might argue that they were excluded despite holding the token at the cutoff block. They might have received the NFT from a friend or mint contract and the transaction might be ambiguous about intent. They might have held a wrapped or derivative version of the token rather than the primary mint. Solscan’s blockchain transparency creates a framework for resolving these disputes fairly.

When a user contests their eligibility, the first step is to have them provide their wallet address. The airdrop team then looks up that address on Solscan and traces its transaction history in the relevant token. The explorer’s transaction details—including input and output accounts, amounts, timestamps, and block heights—create a clear record. If a transaction occurred before the cutoff and the user held a positive balance through the cutoff block, the case for inclusion is strong. If the transaction occurred after the cutoff or if the wallet held a balance of zero at the cutoff height, exclusion is justified.

More complex cases involve wrapped tokens, bridge tokens, or staked representations. Some users might have held the eligible token in a stake account or liquidity pool rather than in a personal wallet. A decentralized finance (DeFi) platform might have consolidated many users’ tokens into a single master account, making individual user holdings invisible at the blockchain level. In these situations, the airdrop team must decide whether to include the accounts, manually verify staking records, or accept that some users will be unable to claim. Communicating this limitation upfront, with examples and clear instructions for users to verify their own status on Solscan, reduces disputes and demonstrates integrity.

The most defensible approach is to publish the eligibility criteria and the block height, conduct the snapshot using Solscan’s historical data APIs, publish the resulting list of eligible addresses, and invite the community to audit it. If a user believes they should be included, they can look up their address on Solscan, confirm they held the token at the target block, and present this evidence. The airdrop team can then review the claim against their methodology and either correct the list or explain why the address did not meet the stated criteria.

API usage and data export workflows for large airdrops

For airdrops distributing tokens to hundreds of thousands of addresses, manually querying Solscan’s web interface for each address is impractical. Solscan provides a public API that supports batch queries and historical data retrieval. An airdrop team can use the API to request account states, token balances, and transaction histories for multiple addresses simultaneously, subject to rate limits and query complexity constraints.

The workflow typically involves writing a script or using a third-party data service to iterate through all mint addresses in a token collection, query the token accounts holding those mints at the target block height, and compile a list of addresses and their balances. The result is a structured dataset—often a CSV file or JSON object—that can be imported into the airdrop distribution contract or script. Solscan’s API documentation details the specific endpoints, rate limits, and response formats, allowing teams to design workflows that work within these constraints.

Solscan also offers data export features, including the ability to download transaction and holder lists for analysis. These exports respect the same read-only, transparent principles as the web interface. A team can download the list of all holders of a token, along with their balances, and then filter or transform this data to match their specific eligibility criteria. The export might include current balances, but the team can reconcile these against the transaction history to determine holdings at the target block.

One critical best practice is to perform a sanity check on the exported data. Does the holder count match expectations? Are there obvious anomalies, such as a single address holding an implausibly large percentage of the token supply? Do the transaction patterns suggest that the data was queried at the intended block height? By cross-referencing the API output with spot checks on the web interface—looking up a few random addresses manually to confirm their balances—a team can gain confidence in the data’s accuracy before proceeding to airdrop distribution.

Documenting and publishing your airdrop methodology for community trust

The final and often-overlooked step is transparent communication about how the airdrop eligibility was determined. A strong announcement should include the block height cutoff, the token or NFT collection mint addresses, the minimum holdings required for eligibility, the date and time the snapshot was taken, and the process used to export and verify the data. For example: «All addresses holding at least 10 XYZ tokens as of Solana block 215,450,000 (approximately June 15, 2024, 14:00 UTC) are eligible. The eligibility list was generated using Solscan’s API to query account state at the specified block height.»

This level of detail matters because it allows anyone to independently verify the airdrop’s fairness. A community member can look up block 215,450,000 on Solscan, see its timestamp, and confirm that the date matches the announcement. They can navigate to the token’s page and examine the holder list. They can look up their own address and check whether they held the token at that block. This public verifiability is not just a feature of Solscan; it is a fundamental property of blockchains and a key advantage of conducting airdrops on-chain rather than through centralized channels.

It is also valuable to publish the raw eligibility list (or a significant sample of it) and invite audits. Announce a claim period during which users can challenge their exclusion. Provide a simple process for users to check their status and file disputes. This openness builds confidence that the airdrop was not conducted arbitrarily. Even if disputes are rare, the existence of a fair appeal process demonstrates that the team stands behind the methodology.

Finally, document any assumptions or limitations. If certain contract accounts were excluded, explain why. If wrapped tokens were treated differently from primary tokens, state that clearly. If the team used a particular tool or script to query Solscan’s API, consider open-sourcing it so others can run the same analysis. The more transparent the process, the more defensible the airdrop and the stronger the community’s confidence in the project.

Common pitfalls and how to avoid them

The most frequent error is confusing block height with timestamp. Solana produces blocks roughly every 400 milliseconds, so small differences in the stated block height can correspond to differences of minutes or hours. If an airdrop announcement says «as of June 15 at 14:00 UTC,» the team must convert this time to the exact Solana block height that occurred at that moment. Solscan’s block explorer shows both block number and timestamp, making the conversion straightforward; however, if the conversion is done incorrectly or if the team queries the wrong block, the eligibility window can be off by thousands of blocks or more. The result is that addresses eligible by the intended rule are excluded, or ineligible addresses are included. Always double-check the block height by looking it up on Solscan.

A second pitfall is failing to account for the existence of multiple token mints or collections. A user might own an NFT from a different collection with a similar name or might hold a bridged or wrapped version of a token from another blockchain. If the airdrop criteria specify «holders of XYZ NFTs,» the team must ensure that the eligibility query targets all and only the intended NFT mints. If a user held a token labeled «XYZ» but from a different mint address, inclusion or exclusion depends on whether that mint was part of the collection. Document the exact mint addresses included in the airdrop and verify that no similar tokens with different mints are accidentally included or excluded.

A third pitfall involves staking or locked tokens. If users locked tokens in a smart contract or staking pool before the airdrop cutoff, those tokens might not appear as direct holdings in their personal wallets at the target block. The airdrop team must decide whether to include staked tokens and, if so, how to identify them. This decision should be announced in advance so users know whether to unstake or migrate their tokens before the eligibility window closes.

Finally, teams sometimes fail to test their eligibility determination process on a small scale before running it on the full dataset. A test run against a subset of addresses or a different token can reveal logical errors, API issues, or data misalignments before committing to a final list. Solscan’s interface and API make this testing straightforward; there is no excuse for shipping a flawed snapshot.