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

# Look up a wallet

> GET /v1/wallet/{address}

Returns every identity attached to a single address. Costs **1 match credit if the address resolves** to an X handle or a Farcaster account, and nothing if it does not.

For more than a handful of addresses use [batch](/api-reference/batch) instead.

## Path parameters

<ParamField path="address" type="string" required>
  An address as `0x` followed by 40 hex characters. Case-insensitive; returned
  lowercased.
</ParamField>

## Request

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

## Response

<ResponseField name="data" type="object | null">
  The record, or `null` when nothing is attached to the address.

  <Expandable title="properties">
    <ResponseField name="wallet" type="string">Lowercased address. Always present.</ResponseField>
    <ResponseField name="ens_name" type="string">Primary ENS name.</ResponseField>

    <ResponseField name="twitter" type="object">
      `handle`, `url`, `verified`, and, once we have checked, `reachable`, `reachability` and `reachability_checked_at`. See [the verified flags](/concepts/data-quality#the-verified-flags), which are narrower than they look, and [when a handle stops being true](/concepts/data-quality#when-a-handle-stops-being-true).

      `also`, an object with `handle`, `url` and `source`, is present only where a second X account is attested for the same wallet and both accounts are live. See [a second X account](#a-second-x-account).
    </ResponseField>

    <ResponseField name="farcaster" type="object">
      `username`, `url`, `followers`, `fid`, and `verified`.
    </ResponseField>

    <ResponseField name="lens" type="string">Lens handle.</ResponseField>
    <ResponseField name="github" type="string">GitHub username.</ResponseField>

    <ResponseField name="sources" type="string[]">
      Evidence classes backing the record: `onchain`, `farcaster`, `attested-social`, `manual`, `aggregated`. See [evidence classes](/concepts/data-quality#evidence-classes).
    </ResponseField>

    <ResponseField name="agent" type="object">
      Present only when the address is a known onchain agent. Carries `is_agent`, `name`, `framework`, `type`, `token_symbol` and `verified`.

      Absent where the address owner attested an identity that is not the agent’s own. A catalog entry is a third party’s claim about an address; an attestation is the owner’s, and the address a launch protocol files against an agent is frequently its creator’s rather than the agent's. Absent means we decline to say, not that we checked and it is not an agent.
    </ResponseField>

    <ResponseField name="quality" type="object">
      `score` from 0 to 100, and `last_verified`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="properties">
    <ResponseField name="wallet" type="string">
      The normalized address you asked for.
    </ResponseField>

    <ResponseField name="found" type="boolean">
      Whether any identities were attached.
    </ResponseField>

    <ResponseField name="last_updated" type="string">
      When the record last changed. Present only when `found` is true.
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      Whether the record is past its freshness window. Present only when `found`
      is true.
    </ResponseField>

    <ResponseField name="checked_at" type="string | null">
      Present only when `found` is false. A timestamp means we checked and found
      nothing; `null` means we have never seen this address.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```json Found theme={null}
  {
    "data": {
      "wallet": "0x00000000000000000000000000000000000000a1",
      "ens_name": "example.eth",
      "twitter": {
        "handle": "example_user",
        "url": "https://x.com/example_user",
        "verified": true,
        "reachable": true,
        "reachability": "live",
        "reachability_checked_at": "2026-08-17T09:41:02.000Z"
      },
      "farcaster": {
        "username": "example",
        "url": "https://warpcast.com/example",
        "followers": 123456,
        "fid": 900001,
        "verified": true
      },
      "sources": ["onchain", "farcaster"],
      "quality": {
        "score": 90,
        "last_verified": "2026-08-10T09:12:00.000Z"
      }
    },
    "meta": {
      "wallet": "0x00000000000000000000000000000000000000a1",
      "found": true,
      "last_updated": "2026-08-10T09:12:00.000Z",
      "stale": false
    }
  }
  ```

  ```json Checked, nothing found theme={null}
  {
    "data": null,
    "meta": {
      "wallet": "0x0000000000000000000000000000000000000001",
      "found": false,
      "checked_at": "2026-07-02T11:30:00.000Z"
    }
  }
  ```

  ```json Never seen theme={null}
  {
    "data": null,
    "meta": {
      "wallet": "0x0000000000000000000000000000000000000002",
      "found": false,
      "checked_at": null
    }
  }
  ```
</CodeGroup>

<Note>
  All three of these are HTTP **200**. A wallet with nothing attached is a
  successful lookup with a negative answer, not an error.
</Note>

## A second X account

A wallet can have two X accounts attested for it: one through a Farcaster
verification, say, and a different one through a signed attestation made later.
When we have checked both and both still reach someone, there is no evidence
for preferring either, so the record keeps its `handle` and carries the other
as `twitter.also`.

```json theme={null}
"twitter": {
  "handle": "someone",
  "url": "https://x.com/someone",
  "verified": true,
  "reachable": true,
  "reachability": "live",
  "reachability_checked_at": "2026-08-17T09:41:02.000Z",
  "also": {
    "handle": "someone_eth",
    "url": "https://x.com/someone_eth",
    "source": "attested-social"
  }
}
```

`source` is the [evidence class](/concepts/data-quality#evidence-classes) of
the attestation behind the second handle. The field is absent, not null, on
every other record. It never appears where the stored handle has stopped
reaching anyone: that record is corrected instead, and `handle` becomes the
account that still works.

## Staleness headers

When a record is past its freshness window the response adds:

```
X-Data-Staleness: stale
X-Last-Updated: 2026-05-01T00:00:00.000Z
```

Both are absent on fresh records, so test for presence rather than comparing values.

## Errors

`INVALID_ADDRESS`, plus the [standard errors](/api-reference/errors).