> ## 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.

# walletlink.social

> Resolve wallet addresses to the people behind them, in both directions.

walletlink turns wallet addresses into social identities: Farcaster usernames, X handles, ENS names, and the follower counts that tell you which of them carry reach.

It works in two directions, and the second one is the reason most people end up here.

## The index

Everything here rests on one thing, and the docs refer to it constantly, so it is worth defining before anything else.

**The index is our own database of wallet identities.** It is not a cache in front of somebody else’s API, and it is not assembled per request. It is 4.85 million wallets that we resolved, verified and stored ourselves, including complete coverage of the Farcaster protocol, and it is refreshed every day.

That is what makes a lookup fast: for most addresses the answer already exists before you ask. It is also what a match rate is measured against, what a fast scan reads, what a deep scan adds to, and what [`GET /api/v1/stats`](/api-reference/stats) reports on. Wherever these pages say “the index”, this is what they mean.

<Note>
  Every API call answers from the index. That is why responses come back in
  milliseconds rather than in the seconds a live resolution would take, and why
  the API's coverage is the index's coverage. See [scan
  depth](/concepts/scan-depth) for the one place that distinction matters.
</Note>

<CardGroup cols={2}>
  <Card title="Forward" icon="arrow-right">
    Given a wallet, find the identities attached to it. You have a holder
    snapshot, an airdrop list, or a CSV export, and you want to know who those
    addresses belong to.
  </Card>

  <Card title="Reverse" icon="arrow-left">
    Given an X handle or a Farcaster username, find the wallets attached to it.
    This is the direction that answers “does this person already hold our
    token”.
  </Card>
</CardGroup>

## Getting data in

There are three ways to hand us a set of addresses, and they are equivalent once the lookup starts.

| Method              | Good for                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| **CSV upload**      | Holder snapshots and exports. Balance columns are detected automatically and used for priority scoring. |
| **Contract import** | You have a contract address but not a holder list. We pull the holders for you.                         |
| **Paste addresses** | Quick one-off checks.                                                                                   |

[Running a lookup](/app/lookups) covers all three in full, along with the supported networks, what a lookup costs in matches, and what comes back out.

## Before you build

Two pages are worth reading before you wire anything up, because they set expectations that the API itself cannot.

<CardGroup cols={2}>
  <Card title="Coverage" icon="chart-pie" href="/concepts/coverage">
    What fraction of a typical wallet list resolves, and why “has an identity”
    and “is reachable” are different numbers.
  </Card>

  <Card title="Data quality" icon="shield-check" href="/concepts/data-quality">
    How matches are attested, what the quality score means, and when a record is
    considered stale.
  </Card>

  <Card title="Scan depth" icon="bolt" href="/concepts/scan-depth">
    Fast reads the index, deep asks every live source. Which one you want, and
    why the API only ever does the first.
  </Card>
</CardGroup>

## The API

Programmatic access is included with every credit pack, drawing on the same balance as the app. Start at the [API introduction](/api-reference/introduction), or jump to the endpoint you need.

<Card title="Look up a wallet" icon="code" href="/api-reference/wallet">
  `GET /api/v1/wallet/{address}`
</Card>

## Getting help

Email [help@walletlink.social](mailto:help@walletlink.social). If you are reporting an API problem, include the `code` from the error response and the endpoint you called.