Skip to main content
Every record carries metadata about how much to trust it. Using it is optional, and for most outreach work the defaults are fine, but if you are making automated decisions you should read this page.

​
Evidence classes

Responses include a sources array describing what kind of evidence backs the record, not which system produced it. A record can carry more than one. More classes generally means more confidence, and aggregated on its own is the weakest position a record can be in.

​
The quality score

quality.score is an integer from 0 to 100 combining how many identities are attached to a wallet and how strong the evidence is for each. The bands are guidance, not thresholds enforced anywhere in the API. Pick your own cutoff based on how expensive a wrong contact is for you.

​
The verified flags

twitter.verified and farcaster.verified are narrower than the English word suggests, and this is the piece most likely to trip you up.
twitter.verified: true does not mean the X account confirmed the link. Since 20 September 2026 the flag is true for every attested route, the Farcaster verification included, and that covers an ENS or Basename text record, where the wallet owner typed the handle and the account never took part. A handle that rests on nothing else also carries self_declared: true: see self-declared handles.
To judge attestation, read the sources array. To judge overall confidence, read quality.score. The verified booleans are not a general trust flag.

​
Self-declared handles

Some attested routes check only the wallet half. An ENS or Basename text record, a governance profile and a Lens profile are all published by the wallet’s owner, so they prove the owner chose to name the handle. Nothing in them proves the X account agreed: anyone can type any handle into their own record. When every source behind a record is of that kind, the twitter object says so:
The field is omitted otherwise, and absent is not false. Evidence classes are recorded per wallet, not per handle, so a record that pairs such a record with a route that checks the account, like a Farcaster verification or a sign-in, cannot say which one supplied the handle. It omits the field rather than claim the account confirmed it. It matters most on a reverse lookup. A wallet returned for @someone with self_declared: true is a wallet whose owner claims the handle, not one the account claimed.

​
Staleness

Records carry a freshness window, and a record is treated as stale once it passes that window or has gone more than 30 days without an update. On GET /api/v1/wallet/{address} this surfaces in two places:
  • meta.stale, a boolean in the response body.
  • X-Data-Staleness: stale and X-Last-Updated, response headers, sent only when the record is stale.
Stale does not mean wrong. It means we have not re-confirmed it recently. Farcaster records refresh daily, so they rarely go stale. Onchain records are only re-read on a slower cycle, because they change rarely and reading them is expensive.

​
When a handle stops being true

An attestation records what was true when the owner made it. An X handle is a name its owner can change at any time, and changing it breaks nothing on their side, so nothing announces it. This has a consequence worth stating plainly, because it is the one way an attested match can be wrong. If someone verified @alice and later renamed to @alice_eth, an attestation that stored only the string still says @alice. That name is now free, somebody else may hold it, and the record has quietly stopped pointing at the person who made it.

​
We check, and we tell you

Every X handle we hold is now resolved against X itself, and the answer travels with the record.
The three fields are absent, not false, when we have not checked. That is the same rule the verified flags follow, for the same reason. suspended and unclaimed are kept apart because they mean different things. A suspended account still belongs to the same person and may come back. A freed name may already belong to somebody else, which is the only case where an old record can point at a stranger rather than at nobody. reassigned is that case, confirmed rather than suspected. Where a source recorded the numeric account id alongside the wallet, we can compare it against the id the name resolves to today, and a mismatch is proof the name has moved on. It is the only state where the record looks perfectly healthy: the name resolves, to a real and active account, and that account is not the one that attested it. reachable is false for it, and the handle export leaves it out.

​
What we found when we checked

We have resolved 482,968 handles against X itself, and 99.9% of the distinct handles the index holds carry a state today; new arrivals and retries join the same daily check. The shares below are of the handles that returned a state. Roughly a third of every attested X handle reaches nobody. That is not a statement about our index in particular. It is a property of the underlying attestation: Farcaster records a verified X account as a name captured once, with no account id and no recheck, so nothing in the protocol notices a rename or a suspension. Any product built on those verifications carries the same third, and without checking there is no way to know which third. Checking does not weaken the attestation. It completes it. “The owner attested this, and it still works” is a stronger statement than either half, and it is one only a source that actually looked can make.

​
Two more things follow from it

We store the account id where a route provides one. An id is permanent in a way a name is not. Routes that carry one let us follow a rename instead of losing it, and attested-social is the route that carries one today. We record every disagreement, and settle only the one kind that is not a judgment call. When two owner-attested routes name different accounts for one wallet, that is evidence something moved. The conflicting account id is never written beside a handle it does not belong to, and the disagreement is kept. We settle a disagreement only where the evidence decides it, and the evidence can decide it two ways. Where the handle we hold reaches nobody and the other one is live on a recent check, we follow the rename. Where the handle we hold still resolves but to a different account than the one the owner attested, the name was freed and re-registered: “live” is true of the string and false of the person, and we follow the owner. In both settled cases the replaced handle is kept, so the change can be explained rather than appearing as a correction out of nowhere. Everywhere else, including where both accounts are live, we keep the handle the record already had and settle nothing: a handle that still reaches its owner is never replaced on the strength of a newer claim alone, however well that claim is attested, because the newer claim is exactly what a stolen key would produce. If you are running outreach on a list you enriched a while ago, re-check it rather than assuming a handle that was attested is still live. meta.stale and X-Data-Staleness tell you when we last re-confirmed a record.

​
Found, missing, and checked

There is a distinction worth respecting between “we have never looked at this wallet” and “we looked and there was nothing”. Both return found: false, and meta.checked_at separates them:
A null means we have no record of ever checking this address. A timestamp means we did check, on that date, and found no identities attached. The second case is a real answer. If you are enriching a list incrementally, a wallet with a recent checked_at is not worth re-submitting, while a null is. Ignoring the distinction costs you nothing in credits, since a miss is never billed, but it does spend rate limit and wall clock rediscovering answers you already hold.
Wallets we have checked and found nothing for are reported as not found rather than as an empty record. A miss is never charged, and you also never receive a hollow object that looks like a match. Those are the two halves of the same promise: we only bill for wallets we actually resolved.