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

# Quickstart

> From nothing to your first resolved wallet.

## Without writing code

Open [walletlink.social](https://walletlink.social), give it addresses one of three ways, and export the results. Your first 100 matches are free in every rolling 30-day window. A match is a wallet resolved to an X handle or a Farcaster account; a miss costs nothing.

<Steps>
  <Step title="Add addresses">
    Upload a CSV or paste addresses directly, free. Importing a contract’s
    holders by address comes with any pack, and a CSV with a balance or value
    column gets priority scoring, also a pack feature.
  </Step>

  <Step title="Choose how hard to look">
    **Deep scan** is the default and finds the most. **Fast** answers from the
    index alone and returns in seconds. See [scan depth](/concepts/scan-depth).
  </Step>

  <Step title="Run the lookup">
    Progress streams as it goes. Large lists keep working while you watch.
  </Step>

  <Step title="Export">
    Full CSV sorted by priority score, or a plain handle list ready for an X
    list import. The CSV is not gated: a free lookup downloads every row it
    produced, with the priority score and follower count columns blank. The
    handle list export comes with any pack.
  </Step>
</Steps>

Reverse lookup works in the app too, and is included with every credit pack. Enter an X handle or a Farcaster username and you get the wallets attached to that person, in the same table with the same export. Results are capped at 100 and ordered by Farcaster reach, matching [the API](/api-reference/reverse-twitter).

## With the API

### Get a key

API access is included with every credit pack, drawing on the same balance.

Sign in at [walletlink.social](https://walletlink.social), open the account menu in the top right, and choose **API keys**. Name the key after wherever it will run, so a leaked one is easy to trace, then copy it.

Keys look like `wts_live_` followed by 32 characters. You can hold up to 10 active keys at a time.

<Warning>
  The key is shown once, at creation, and only its hash is stored. If you lose
  it we cannot recover it, only replace it. Treat it as a server-side secret: it
  carries your whole credit balance and there is no per-key spend cap. A leaked
  key can spend every match you have bought.
</Warning>

### Make a call

```bash theme={null}
curl https://walletlink.social/api/v1/wallet/0x00000000000000000000000000000000000000a1 \
  -H "Authorization: Bearer wts_live_YOUR_KEY"
```

The `Bearer` prefix is optional. A bare key in the `Authorization` header works too.

### Read the response

```json theme={null}
{
  "data": {
    "wallet": "0x00000000000000000000000000000000000000a1",
    "ens_name": "example.eth",
    "farcaster": {
      "username": "example",
      "url": "https://warpcast.com/example",
      "followers": 123456,
      "fid": 900001,
      "verified": true
    },
    "sources": ["onchain", "farcaster"],
    "quality": { "score": 75, "last_verified": "2026-08-01T00:00:00.000Z" }
  },
  "meta": {
    "wallet": "0x00000000000000000000000000000000000000a1",
    "found": true,
    "last_updated": "2026-08-01T00:00:00.000Z",
    "stale": false
  }
}
```

Every response is `{ data, meta }`. Fields with no value are omitted rather than returned as `null`, so check for presence rather than assuming a fixed shape.

<Note>
  A wallet with no identities returns HTTP **200** with `data: null`, not a 404.
  Only genuine failures use error status codes.
</Note>

### Go bigger

One address at a time gets slow quickly. [`POST /api/v1/batch`](/api-reference/batch) takes up to 50 addresses per request on the default plan (a live Scale or Index pack raises the ceiling):

```bash theme={null}
curl -X POST https://walletlink.social/api/v1/batch \
  -H "Authorization: Bearer wts_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallets": ["0xd8da...", "0x1234..."]}'
```

## Next steps

<CardGroup cols={2}>
  <Card title="API introduction" icon="book" href="/api-reference/introduction">
    Auth, plans, credits and conventions.
  </Card>

  <Card title="Coverage" icon="chart-pie" href="/concepts/coverage">
    What match rate to expect before you build around one.
  </Card>
</CardGroup>