Running a lookup

Everything here happens at walletlink.social with no code. The API covers the same ground programmatically, with one difference noted under scan depth.

​

Getting addresses in

Three routes, equivalent once the lookup starts.

​

Files

A CSV or .xlsx is scanned for a wallet column, and any balance or value column is detected automatically and used for priority scoring. Other columns come along unchanged and appear in the export, so a list arriving with a tier or a cohort label leaves with it.

​

Pasting

Addresses are extracted by pattern, so a block of text with addresses scattered through it works as well as a clean list. Duplicates are removed.

​

Contract import

We cover eight networks: Ethereum, Base, Robinhood Chain, Arbitrum, Polygon, Optimism, BNB Chain and HyperEVM. Both NFT collections and token contracts are supported on all eight. Token holder lists have more than one index behind them. If the primary one is unavailable, the import is served from a second index, behind that a third, and behind those a public backup, so a spent daily ceiling no longer stops the feature. One network sits outside the full arrangement: HyperEVM has exactly one index, so a problem with it pauses token import on that network rather than falling back. NFT collections are unaffected by a spent ceiling on every network, because they do not resolve through those indexes. The backup is slower and returns fewer holders, so a list served from it is more often partial. It is marked truncated exactly as any other partial list is, so the flag on the result stays the thing to trust rather than the size of the list. If you need the complete set, run the import again once the primary index is serving.

​

How much a lookup costs

You are charged for matches, not for addresses submitted. A match is a wallet we resolve to an X handle or a Farcaster account. A wallet we cannot resolve costs nothing, so a list with a low match rate costs you less rather than the same. Credits are cumulative and account-wide, not per lookup: twenty runs of 500 addresses draw exactly what one run of 10,000 draws. They last 12 months from purchase, and every pack is a one-time payment, not a subscription. The free allowance rolls rather than resetting: each match frees up again 30 days after it was spent, so credits return a few at a time rather than the whole allowance coming back on a fixed date. It is there to try the product. Contract import, reverse lookup, deep scan with onchain ENS, priority score, follower counts, the X list export, growing a saved lookup, Farcaster DMs from the app and the API need a pack. The packs differ only in how many matches they hold; nothing is gated by pack size.

​

Limits on addresses

A few limits are on addresses rather than matches, and which one applies depends on how you are signed in.

• Not signed in: 500 addresses per lookup, plus a rate limit per IP address. There is no account-wide quota, because there is no account; instead each lookup opens at most 50 matches, and the rest appear as locked rows. Sign in and buy a pack to open them, on that same lookup.
• Signed in, on the free allowance: 500 addresses per lookup, or ten times your remaining free matches, whichever is lower.
• Holding a pack: no per-lookup cap. A submission may be at most ten times your remaining matches.

The ten-times rule is a guard against submitting a million junk addresses to burn our upstream credits for free, not a quota. At a typical match rate a real list needs about four times, so it will not affect you. Without an account the same gate is per lookup: the first 50 matches are open, and everything past them is locked. An account is always the better deal, because the allowance meters matches, not lookups.

​

When a lookup finds more than your balance covers

Because addresses are bounded at ten times your remaining matches, a high-hit-rate list can find more matches than you have left. This is true of pack credits as well as the free allowance. The lookup still runs in full. The matches your balance covered are open in the result; the rest appear as locked rows: the wallet stays, along with anything never billed (an ENS name, a Lens or GitHub account), and the X handle or Farcaster account is withheld. You are charged only for the open matches. A little headroom is built in. A match rate cannot be known before a lookup runs, so a list sized honestly against a pack can still overshoot it; a small margin past your balance is delivered and not charged for, and only a real overshoot is locked. The count you are likely to need is shown next to your file before you start, so a list that will outrun your balance says so first. Importing holders from a contract stops at what your credits cover rather than at the address limit, and the import tells you when that is why it stopped. Locked matches stay with the lookup. Buy a pack and unlock them from the results view: the unlock draws one credit per locked match and opens the same rows, in the live result and in the saved copy alike. The rolling allowance does not open them by itself; the way through the gate is a pack.

​

Choosing how hard to look

Before starting, pick Fast or Deep scan. Deep is the default and finds the most; fast answers from the walletlink index alone and returns in seconds. The estimate on screen follows the choice. Scan depth covers what each one reads and when the cheaper answer is the right one.

​

Keeping the result

A lookup is saved to your history by default, and you can name it while it runs. An unnamed lookup is still saved; the name is there so you can find it again among twenty others. Turn saving off for a one-off, and export before you leave the page: nothing is kept.

​

Growing a saved lookup

With a pack, a saved lookup is a living list rather than a snapshot. Every pack includes this.

• Add addresses to it later. They are resolved and merged into the existing result rather than starting a separate one, so a holder list that grows stays in one place.
• See what is new since you last opened it. The index gains identities every day, so a wallet that resolved to nothing in March may resolve now. Rows that gained an identity since your last visit are marked NEW when you reopen the lookup, which means a list you ran once keeps paying out without you re-running anything.

Added addresses are billed like any others: a match each, and nothing for a miss. On the free allowance a saved lookup is a fixed record: you can open it, rename it, and export it, but its contents do not change.

​

Getting results out

Priority score ranks by holdings weighted by Farcaster reach, so the top of a priority-ranked list is the part worth contacting first. It comes with any pack, along with the follower counts it draws on: on the free allowance both columns are blank, in the table and in the export alike. The CSV export itself is not gated. A free lookup downloads every row it produced, with your original columns and every open identity. A locked row exports like any other, minus the identities it is holding; unlock the lookup and the next export carries them. What a pack adds to the file is those two ranking columns; what it adds beside the file is the handle list export.

​

Reaching people directly

Sending Farcaster direct messages to the resolved list from inside the app, without exporting first, is included with every pack. It needs a Farcaster API key of your own, which the app stores only if you ask it to, and the messages go out under your account, not ours. X has no equivalent: there is no API route for messaging an arbitrary handle, so the handle list export is the path there.

​

Going the other way

Reverse lookup takes an X handle or a Farcaster username and returns the wallets attached to that person. It is included with every credit pack and sits on the front page, and it answers the question that comes up most often before a campaign: does this person already hold our token. Results are capped at 100 and ordered by Farcaster reach, matching the API.