Skip to main content
GET
Reverse Farcaster lookup
Finds every wallet attested 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. Only wallets whose recorded sources are all attested evidence (an onchain record, a Farcaster verification, an owner-signed link) are returned. Sources are recorded per wallet, not per username, so a wallet whose attested link sits beside a correlated source is left out too: we cannot tell which of the two supplied the username. A single-wallet lookup still shows it, with its labels. The total and every page follow the same rule, and an empty result means no such wallet, not that no address is attested anywhere. This lookup needs a key that belongs to an account. A key bought with USDC and no account resolves addresses but answers this one with 403 ACCOUNT_REQUIRED: turning a username into the wallets behind it is the direction that can find a person, so somebody has to answer for the search. Like the reverse X lookup, it is a one-time check of which wallets this account has linked to itself, not a way to follow what a person holds over time, which the terms of service forbid. Because Farcaster coverage is complete, this is the most reliable lookup in the API. An empty result is a statement about attested rows, as above, not a sign that we have not indexed the username yet.

Path parameters

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.

Query parameters

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.

Request

Response

Identical in shape to the reverse X lookup, with farcaster always present instead of twitter, and meta.username instead of meta.handle.
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).
object

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.

Errors

INVALID_USERNAME, INVALID_CURSOR, plus the standard errors.