Skip to main content
GET
Reverse Farcaster lookup
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, 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

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.