Skip to main content
GET
Look up a wallet
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 instead.

Path parameters

string
required
An address as 0x followed by 40 hex characters. Case-insensitive; returned lowercased.

Request

Response

object | null
The record, or null when nothing is attached to the address.
object
All three of these are HTTP 200. A wallet with nothing attached is a successful lookup with a negative answer, not an error.

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.
source is the evidence class 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:
Both are absent on fresh records, so test for presence rather than comparing values.

Errors

INVALID_ADDRESS, plus the standard errors.