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

# Reverse Farcaster lookup

> GET /v1/reverse/farcaster/{username}

Finds every wallet linked to a Farcaster username. Costs **1 match credit per wallet returned**, 100 per page. A username with no wallets attached costs nothing. Separately, each request weighs 2 units against your rate limit.

Because [Farcaster coverage is complete](/concepts/coverage#farcaster-coverage-is-complete), this is the most reliable lookup in the API. An empty result means the username genuinely has no addresses attached, not that we have not indexed it yet.

## Path parameters

<ParamField path="username" type="string" required>
  1 to 32 characters of letters, numbers, dots and hyphens, starting with a letter or a number. Input is lowercased before matching.

  Both kinds of Farcaster name work: a plain fname such as `dwr`, and an ENS name attached to the account such as `vitalik.eth`. A large share of the index is `.eth` names, so pass them through unchanged rather than stripping the suffix.
</ParamField>

## Query parameters

<ParamField query="cursor" type="string">
  Continues a paginated result: pass the `next_cursor` value from the previous
  response, unmodified. Omit it for the first page. A value this API did not
  produce returns `INVALID_CURSOR`.
</ParamField>

## Request

```bash theme={null}
curl https://walletlink.social/api/v1/reverse/farcaster/dwr \
  -H "Authorization: Bearer wts_live_YOUR_KEY"
```

## Response

Identical in shape to the [reverse X lookup](/api-reference/reverse-twitter), with `farcaster` always present instead of `twitter`, and `meta.username` instead of `meta.handle`.

<ResponseField name="data" type="array">
  Matching wallets, at most 100 per page, ordered by Farcaster reach (highest
  follower count first, wallets without one last, wallet address as the
  tiebreak).
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="properties">
    <ResponseField name="username" type="string">
      The normalized, lowercased username.
    </ResponseField>

    <ResponseField name="total_count" type="number">
      Total matches in the index, across all pages.
    </ResponseField>

    <ResponseField name="returned_count" type="number">
      How many are in this response.
    </ResponseField>

    <ResponseField name="truncated" type="boolean">
      Whether more results remain after this page.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      Pass as `cursor` to fetch the next page. `null` on the last page.
    </ResponseField>
  </Expandable>
</ResponseField>

```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": ["farcaster"],
      "quality_score": 65
    }
  ],
  "meta": {
    "username": "example",
    "total_count": 1,
    "returned_count": 1,
    "truncated": false,
    "next_cursor": null
  }
}
```

## Several wallets per account

Multiple results are the normal case here, more so than on X. A Farcaster account has one custody address plus any number of verified addresses, and all of them are indexed. A single active account returning three or four wallets is unremarkable.

The same 100-per-page pagination applies. See [one handle, many wallets](/api-reference/reverse-twitter#one-handle-many-wallets).

## Errors

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