> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletlink.social/llms.txt
> Use this file to discover all available pages before exploring further.
# Running a lookup
> Getting addresses in, choosing how hard to look, and getting results back out.
Everything here happens at [walletlink.social](https://walletlink.social) with no code. The [API](/api-reference/introduction) covers the same ground programmatically, with one difference noted under [scan depth](/concepts/scan-depth).
## Getting addresses in
Three routes, equivalent once the lookup starts.
CSV or Excel. Drop it anywhere on the page.
Any text holding addresses. They are picked out of whatever surrounds them.
Give a contract address, get its holders. Included with every credit pack.
### 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.
HyperEVM NFT holder lists are read from the collection itself, one token at a
time, so a very large collection is refused rather than sampled. If you hit
that, upload the holder list instead: a pasted or uploaded list is resolved
exactly the same way as an imported one.
A holder list can be truncated. Token holder lists in particular come from an
index with its own ceiling, and when a result fills that ceiling exactly we
say so rather than implying the list is complete. Treat a truncation warning
as real: the collection has more holders than you are looking at.
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.
| Pack | Matches | Price |
| --------------------- | ----------------------- | ----- |
| None (free allowance) | 100 per rolling 30 days | \$0 |
| Trial | 250 | \$29 |
| Campaign | 1,500 | \$99 |
| Scale | 6,000 | \$299 |
| Index | 25,000 | \$899 |
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](/#the-index) alone and returns in seconds. The estimate on screen follows the choice.
[Scan depth](/concepts/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
Every column, every row, sorted by priority score. Your original columns are
preserved alongside the resolved identities.
Just the handles, in the shape an X list import expects.
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](/api-reference/reverse-twitter).