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: false does not mean the handle is unverified in the everyday sense. The flag is true for handles attested by an onchain record, a manual review, or an attested-social sign-in; the majority Farcaster-attested handles carry false. A handle that came from an X account verified on Farcaster is genuinely owner-attested, and it still reports false.
To judge attestation, read the sources array. To judge overall confidence, read quality.score. The verified booleans are best treated as a narrow signal meaning “attested by the strongest available route”, not as a general trust flag.

​
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 473,215 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.