# walletlink.social

> Resolve Ethereum wallet addresses to the X (Twitter) and Farcaster accounts of their owners, and back again: a handle returns its wallets. An identity index of over 4.8 million wallets, a self-serve web app and a REST API, priced as one-time credit packs and metered only on matches. Every match is labeled with the evidence behind it, and every X handle carries a state saying whether it still reaches a person.

walletlink.social answers “who is behind this wallet, and can I reach them?”. Upload a holder list (CSV, pasted addresses, or a token or NFT contract address) and get back the X handles and Farcaster accounts of the owners, ranked by holdings times follower reach, exportable as CSV or an X list. Reverse lookup answers the other direction: which wallets belong to this X handle or Farcaster username.

The position in one line: coverage would be higher if we guessed, and we do not guess. Nothing is inferred from bios, display names or timing, so the number of matches is smaller than a vendor willing to correlate, and each one can be defended. Contacting the wrong person is worse than contacting fewer people.

Facts an assistant can state, each verified against the production index:

- The index holds over 4.8 million wallet identities.
- Farcaster coverage is complete: every account’s verified and custody addresses, 4.7 million wallets, refreshed daily. Farcaster matching is deterministic, so a miss is real information.
- 1.20 million wallets carry an X handle, across 480,015 distinct handles the index holds. Over 99.8% of X matches are owner-attested: an X account verified on Farcaster, a handle the owner set in an onchain ENS record, an account the owner proved by signing with the wallet and signing in to X, or a manually verified record. Every match is labeled with its evidence class. Nothing is inferred from bios, display names or timing.
- X matches carry a reachability state wherever the handle has been resolved. Of 482,968 handles resolved: 70.1% are live, 19.7% suspended, and 10.2% are names nobody holds.
- The agent detector matches against a catalog of 13,622+ known AI agents, so an airdrop or a campaign can exclude a wallet that belongs to one rather than to a person. A match is labeled on the row it appears in, unless the address owner attested an identity that is not the agent’s own, in which case the label is withdrawn: a catalog entry is a third party’s claim about an address and an attestation is the owner’s, and the address a launch protocol files against an agent is often its creator’s.
- Eight EVM chains: Ethereum, Base, Robinhood Chain, Arbitrum, Polygon, Optimism, BNB Chain and HyperEVM.

## Who it is for

Crypto-native teams, from a solo founder to about twenty people: NFT projects, token and protocol teams, DAOs, and web3 marketing agencies. The daily user is usually a growth or community lead; at this size the founder is often the same person.

The problem it solves: a holder list is an audience you already earned, and you cannot talk to it, because addresses have no inbox.

The jobs people hire it for:

- Announce something to holders where they already are, without the address list being a dead end.
- Find who the whales behind these wallets are, and reach the ones with an audience.
- Check whether a person already holds the token, before a partnership or an airdrop.
- Exclude AI agent wallets from an airdrop or an allowlist.
- Rank a holder list by who is both invested and heard, rather than by balance alone.

Who it is not for: mass-DM spammers, and anyone targeting people with no relationship to their token. The product returns identity, not a messaging channel. A team with a fifty-wallet list does not need to pay, and that is fine.

## What a match is, and what it costs

A match is a wallet resolved to an X handle or a Farcaster account. Wallets that resolve to nothing, and wallets carrying only an ENS name, a Lens profile or a GitHub account, are never billed. That is the billing unit, on the site and through the API alike; a wallet that resolves only to an ENS name, a Lens profile or a GitHub account is still returned. A list that matches poorly spends almost none of a pack, so there is no penalty for finding out.

Pricing is one-time credit packs. There are no subscriptions, no seats and no minimum. Free is 100 matches per rolling 30 days with a free account, cumulative and account-wide. Packs: Trial $29 for 250 matches (one list, once), Campaign $99 for 1,500 matches (an airdrop or nft collection), Scale $299 for 6,000 matches (several lists, or one large one), Index $899 for 25,000 matches (agencies and repeat work). Every pack includes all eight chains, API access drawing the same credits, an X list export, the wallet addresses behind a handle, priority score and follower counts, contract import, and deep scan with onchain ENS. The CSV export is not gated: a free account downloads every row it produced, though priority score and follower counts are blank in it. Credits last 12 months.

No account is needed before buying: checkout asks for the email the credits and the receipt go to. There are no refunds and no guarantees; the free allowance exists so you can prove the match rate on your own list before paying. A lookup also runs with no account at all, on a capped list size and a few jobs per hour, which is enough to see the shape of a real answer.

## How a match is evidenced

An identity is attested when the wallet owner published the link themselves: a Farcaster verification, an onchain ENS record, an attested-social sign-in, or a manually verified record. Anything else is correlated, and labeled so. Every record carries a sources array describing the kind of evidence behind it, never which system produced it. A record can carry more than one class, and more classes generally means more confidence.

- onchain: published by the address owner in an onchain record.
- farcaster: a protocol-level Farcaster account verification.
- attested-social: the owner proved the wallet with a signature and the account with a sign-in, on an identity platform.
- manual: reviewed by us directly.
- aggregated: correlated from a third-party identity index. Weaker than the others, and the weakest position a record can be in on its own.

Records also carry a quality score from 0 to 100. Seventy and above is strong, forty to sixty-nine is usable, and below forty is thin and should be treated as a lead rather than a fact.

One term that reliably misleads: twitter.verified being true does not mean the X account confirmed the link. Since 20 September 2026 that flag is true for every attested route, including an ENS or Basename text record, where the wallet owner typed the handle and the account never took part. A handle that rests only on such a record also carries self_declared: true, meaning the owner claims the handle and the account never confirmed it. The field is omitted otherwise, and absent is not false.

## Whether the account still reaches a person

Farcaster stores a verified X account as a name, written once, with no account number and no later check. When somebody renames or gets suspended, nothing in the protocol notices, so every tool built on those verifications carries the same dead handles and none of them can say which. We check the handle against the live account and report the answer per record. A checked X handle carries one of four states: live, suspended, unclaimed, or reassigned. A handle can be attested by its owner and suspended today, so a handle is not a promise that anyone is behind it.

- live: the owner attested this account, and the same account still holds the handle.
- suspended: the owner attested it and X has since suspended it. Messages will not arrive.
- unclaimed: the owner attested it and no account holds the name now, usually a rename. Treat it as a lead rather than a contact.
- reassigned: the owner attested it and the name now belongs to a different live account. Messages would reach a stranger, not the wallet owner.

A field that is absent was not measured. Absent is not false: a missing reachability means the handle was not checked, never that nobody is behind it. Reassignment is decided per wallet rather than per handle, because the same name can be correct for one wallet and a stranger for another.

The handle export leaves out the ones we checked and found dead, so a campaign is not sending into accounts that cannot receive it.

## Coverage, in two numbers rather than one

There is no single match rate, and quoting one hides the thing that decides a campaign. The chain matters more than the collection does. Measured on 2026-08-17 against our own index with no external calls: Base 46.2% and Ethereum 16.6% of holders have an X or Farcaster account. Base is roughly three times Ethereum because Base is where Farcaster lives. Use the row for your chain, not an average; the full measured table is machine-readable as match_rates on GET /api/v1/stats.

Keep two separate numbers apart. “Has an identity” counts ENS and Lens and is a resolution rate. “Has an X or Farcaster account” is the smaller of the two, it is the number a campaign plans around, and it is the one that is billed. Tools that match wallets to social accounts typically publish rates in the low single digits.

Having an account and reaching it are different claims again, which is what the reachability section above measures.

## The API

The REST API is the same index and the same credits as the app. Base URL https://walletlink.social/api/v1; a GET on it needs no key and returns a JSON index of the endpoints, with links to the reference and the OpenAPI description. Authentication is an API key in the Authorization header, as a bearer token. Keys are self-serve for any signed-in account, including one spending the free allowance; what a key may draw is decided per call against the same balance.

Nine endpoints: a single wallet lookup, a batch lookup of up to 50 addresses per request on the default plan, an async job submission with a free status poll, a free dry-run estimate over a list (counts only: how many are in the index and the band a resolve would bill inside), reverse lookup by X handle, reverse lookup by Farcaster username, index statistics with the measured per-chain match rates, and your own usage and remaining balance. Reverse results are cursor-paginated. A job runs the same pipeline the app runs, resolving wallets the index has not checked against live sources; it is billed only on matches when it completes, one job may be active per account at a time, and a submission is capped at 10 times the match balance.

Billing follows the same rule as the app. A single lookup costs one match credit when it resolves to X or Farcaster, and nothing when it does not. A batch costs one credit per resolving address, after duplicates are removed. A reverse lookup costs one credit per wallet returned, and nothing when a handle has no wallets. Statistics, usage and the estimate are free of credits, and still require a key; the estimate weighs the rate window like the batch it previews. A key whose balance is zero can still read the free endpoints; the balance and coverage reads keep answering at zero, and only a call that could bill refuses with NO_CREDITS.

Rate limits for a credit-holding account start at 60 requests per minute, 5,000 per day and 50,000 per month, counted across every key on the account so that minting more keys does not raise the ceiling. A live Scale pack raises the account to the 300-per-minute preset with 200-address batches, and a live Index pack to 1000 per minute with 1000-address batches, for the twelve months the pack lives; credits still bound what can be resolved in total. Responses carry the remaining allowance in headers, and a rejected request says when to retry. Errors return a stable machine-readable code alongside the human-readable message.

Full request and response shapes, every error code and the exact header semantics are in the API reference, linked below, rather than repeated here. The machine-readable form is an OpenAPI 3.1 description at https://docs.walletlink.social/openapi.yaml.

## For agents: the MCP server

There is a remote MCP server at https://walletlink.social/api/mcp, so an agent can resolve wallets without a person first reading an API reference. Streamable HTTP, drawing the same credits as everything else. It is listed in the official MCP registry as social.walletlink/wallet-identity, verified by DNS.

Eight tools: resolve addresses to their social identities (up to the key’s plan ceiling per call), estimate a list before spending on it (free counts: what is in the index and what a resolve would bill), submit a background job that resolves unchecked wallets against live sources, poll that job for progress and results, find the wallets behind an X handle, find the wallets behind a Farcaster username, read index coverage, and read the remaining balance on the key. The job poll, the coverage tool, the balance tool and the estimate cost no credits. Every tool description states its own cost, because an agent that cannot see the price cannot spend responsibly.

Two ways to authenticate. OAuth 2.1, which is what a client with a person behind it should use: add the URL, and the first tool call opens a consent screen rather than asking for a key. The server is an OAuth resource server, discovery starts at https://walletlink.social/.well-known/oauth-protected-resource, and it registers clients through both client ID metadata documents and dynamic client registration at https://walletlink.social/api/oauth/register. Every client is public, so PKCE with S256 is required and no client secret is issued. Access tokens last an hour and refresh themselves; a person ends a connection from their account and it stops on the next call.

Or the same bearer key the REST API uses, which is the better answer for a server with no browser to sign in from. Keys are self-serve at https://walletlink.social for any signed-in account, free allowance included, and the keys modal offers a one-click install for Cursor and a one-line command for Claude Code at the moment a key is created.

Tool discovery needs neither: a client can connect and list the tools before buying anything. Calling a tool with no credential answers 401 with a WWW-Authenticate header naming the protected resource metadata, which is the signal to start the flow, rather than a tool error a model would read out and move past. Any request carrying an expired or revoked access token, the handshake included, answers 401 the same way, so a client refreshes and retries.

The skill file is at https://walletlink.social/skill.md, which is a URL a person can hand to an agent directly: what the tools are, what each costs, how to authenticate, and how to read a result. It is generated from the same constants and canonical sentences as this file, so it cannot drift from what the product actually charges or claims.

There is also an Apify Actor at https://apify.com/starl3xx/wallet-to-twitter-farcaster-lookup, which wraps the same REST API for a scraping marketplace. It is free to run and takes the caller’s own key, so it draws the same free allowance and the same packs rather than a second balance.

## For agents: buying credits with USDC, no account

An agent can buy its own credits over x402, with no account, no card and no email. POST to https://walletlink.social/api/x402/buy and it answers 402 with a payment challenge; pay $1.00 in USDC on Base and the response carries a fresh API key with 12 match credits behind it. That is roughly 51 resolvable addresses at our measured rate, or one full batch call, at about $0.0198 an address. The key resolves addresses; the reverse lookups, a handle to the wallets behind it, need an account and answer it with 403 ACCOUNT_REQUIRED.

One settlement can buy more: send {"quantity": N}, 1 to 25, and the challenge, the payment and the grant all scale linearly, so N packs cost N signatures’ worth of nothing extra. A buy that carries a valid wts_live_ key in the Authorization header is a top-up: the credits land on that key’s account and no new key is minted, which is how an agent recovers from a 402 mid-session without a second credential. An OAuth token cannot buy, there or anywhere. Every 10th settled purchase from the same wallet grants one bonus pack of matches, on the settlement history of that wallet alone.

The credits are the same ones a card buys and are metered the same way, so an address that resolves to nobody still costs nothing. The key works on the REST API and on the MCP server, with one exception: a key bought with no account behind it cannot use the reverse lookups, which answer 403 ACCOUNT_REQUIRED, because turning a handle into wallets needs an account somebody answers for.

The 402 challenge also names the terms of service, at https://walletlink.social/terms, and their version, in the payment request itself, in the response body and in a Link header. Paying the challenge accepts them; nothing extra is sent to do so, and the credits record the version in force when the payment settled.

The key is shown once. If it is lost, sign a challenge with the wallet that paid at https://walletlink.social/api/x402/recover and a new one is issued against the same credits; the credits belong to the account rather than to the key. Signing is required because every field of a settled payment is public onchain, so a payment cannot prove who is holding the wallet afterwards.

## Product

- [Wallet lookup](https://walletlink.social/): the app. Upload a holder list or a contract address, get the reachable people behind it, ranked, with the evidence on every row.
- [Find the X (Twitter) account behind a wallet](https://walletlink.social/find-twitter-account-from-wallet-address): free, no account. Paste one EVM wallet address and see the X handle and Farcaster account its owner published, labeled attested or correlated. For a list, use the app above.
- [Handle check](https://walletlink.social/check): free, no account. Check whether an X handle verified on Farcaster still reaches anyone. Returns how many wallets in the index carry it, never which ones.
- [Pricing](https://walletlink.social/pricing): the packs, the free allowance, what counts as a match, and the questions people ask before buying.
- [Holder reports](https://walletlink.social/holders): per-collection reachability reports on named token and NFT contracts, grouped by chain. Aggregates only, never wallet or handle lists.
- [Blog](https://walletlink.social/blog): guides on holder outreach, airdrop targeting, Farcaster, and wallet identity.

Individual holder reports live at /holders/{chain}/{contract address}, for example [The Warplets on Base](https://walletlink.social/holders/base/0x699727f9e01a822efdcf7333073f0461e5914b4e) and [CRYPTOPUNKS on Ethereum](https://walletlink.social/holders/ethereum/0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb). Each report gives the holder count, how many were measured, the identity and reachability split, follower distribution, and the collections those holders overlap with.

## Docs and API

- [Documentation](https://docs.walletlink.social/): product and API docs. Every page is also served as markdown by appending .md to its URL.
- [Quickstart](https://docs.walletlink.social/quickstart.md): from nothing to your first resolved wallet, by upload and by API call.
- [Running a lookup](https://docs.walletlink.social/app/lookups.md): getting addresses in, choosing a scan, and getting results out.
- [Scan depth](https://docs.walletlink.social/concepts/scan-depth.md): fast is the index alone; deep adds live sources including onchain ENS records.
- [Coverage](https://docs.walletlink.social/concepts/coverage.md): what fraction of a wallet list resolves, per chain, and what the number actually means.
- [Data quality](https://docs.walletlink.social/concepts/data-quality.md): evidence classes, the quality score, reachability states, and when a record goes stale.
- [API reference](https://docs.walletlink.social/api-reference/introduction.md): base URL, authentication and conventions, then one page per endpoint.
- [MCP server](https://docs.walletlink.social/mcp-server.md): eight tools for agents, what each costs, and the config block for Claude and Cursor.
- [Agent pack over x402](https://docs.walletlink.social/agent-pack.md): buy credits with USDC on Base, no account, and how to recover a lost key.
- [OpenAPI description](https://docs.walletlink.social/openapi.yaml): the whole REST surface as OpenAPI 3.1, for SDK generation and tool discovery.
- [Full docs for LLMs](https://docs.walletlink.social/llms-full.txt): the complete documentation in one file.

## Comparisons

Claim-by-claim comparisons with the alternatives, maintained and dated:

- [All comparisons](https://walletlink.social/vs): the hub over the eight pages below, split by whether the service still exists.
- [walletlink vs Absolute Labs](https://walletlink.social/vs/absolute-labs): a wallet relationship management platform sold by demo, with no price published anywhere on its site. Different purchase.
- [walletlink vs Addressable](https://walletlink.social/vs/addressable): deterministic and owner-attested against probabilistic fingerprinting, and self-serve against a sales call.
- [walletlink vs Cookie3](https://walletlink.social/vs/cookie3): their wallet-to-X matching caps at ten thousand accounts on every tier a person can buy. Cookie3 is not Cookie.fun; the page says so explicitly.
- [walletlink vs Formo](https://walletlink.social/vs/formo): Formo is product analytics for your own app, billed per request whether or not an address resolves. Different purchase.
- [walletlink vs Nansen](https://walletlink.social/vs/nansen): Nansen answers what a wallet does; its address API returns behavior and labels and no social account. We answer who published it.
- [walletlink vs Holder](https://walletlink.social/vs/holder): Holder sunset in June 2024. A migration page, with no subscription to replace.
- [walletlink vs Blaze](https://walletlink.social/vs/blaze): Blaze is no longer available. The page records the comparison for the searches that still land on it.
- [walletlink vs Airstack](https://walletlink.social/vs/airstack): Airstack is no longer available, and its Farcaster APIs were deprecated before that. Same treatment.

A note on the name: walletlink.social is not WalletLink, the wallet-connection protocol Coinbase shipped and later renamed to the Coinbase Wallet SDK. This is an identity index, not a connector.

## Guides

The blog is the question-shaped half of the site. Every post is public, dated and open. Every post is also served as markdown by appending .md to its URL, which is the form linked below; drop the .md for the page a person reads. The whole corpus is one file at https://walletlink.social/llms-full.txt.

- [The 22% identity rate: how we got far past single digits](https://walletlink.social/blog/twenty-two-percent-match-rate.md): where the number comes from, and why it is a range rather than an average.
- [How Farcaster verified addresses changed wallet identity](https://walletlink.social/blog/farcaster-verified-addresses.md): the protocol mechanism the whole deterministic half rests on.
- [We scraped 13,622 AI agent wallets. Here’s what we found](https://walletlink.social/blog/ai-agent-wallets-what-we-found.md): the sweep that built the agent list, and what an agent wallet looks like in holder data. The count in the title records that run; the current figure is above.
- [AI agents on your holder list: why it matters](https://walletlink.social/blog/ai-agents-why-it-matters.md): why a holder count that includes agents overstates an audience.
- [How to filter AI agent wallets before your next airdrop](https://walletlink.social/blog/filter-agents-before-airdrop.md): the exclusion, step by step.
- [The priority score formula: finding your most valuable holders](https://walletlink.social/blog/priority-score-formula.md): holdings multiplied by log10 of followers plus one, and why that shape.
- [The wallet identity stack: ENS, Farcaster, and beyond](https://walletlink.social/blog/wallet-identity-stack.md): which identity layers exist and what each one can prove.
- [Airdrop targeting: why identity beats transaction history](https://walletlink.social/blog/airdrop-targeting-identity.md): targeting people rather than behavior.
- [Sybil resistance through identity: a better approach](https://walletlink.social/blog/sybil-resistance-identity.md): attestation as a filter.
- [How to reach your token holders on Farcaster](https://walletlink.social/blog/reach-holders-on-farcaster.md): the reachable subset, and how to use it.
- [5 ways to use wallet identity for token holder outreach](https://walletlink.social/blog/five-ways-wallet-identity.md): the campaign patterns.
- [Wallet identity for NFT collections: a step-by-step guide](https://walletlink.social/blog/nft-collection-wallet-identity-guide.md): a collection from snapshot to outreach list.
- [Token launch marketing: reaching your earliest holders](https://walletlink.social/blog/token-launch-marketing.md): the launch case.
- [NFT holder engagement: from anonymous wallets to real relationships](https://walletlink.social/blog/nft-holder-engagement.md): retention after mint.
- [Community retention: the case for direct holder outreach](https://walletlink.social/blog/community-retention-direct-outreach.md): why a channel you own beats a feed.
- [Building an ambassador program with wallet identity data](https://walletlink.social/blog/ambassador-program-wallet-data.md): finding the holders with an audience.
- [Why your DAO has a communication problem, not a participation problem](https://walletlink.social/blog/dao-communication-problem.md): governance turnout, reframed.
- [Case study: how a DAO increased governance participation from 5% to 22%](https://walletlink.social/blog/dao-governance-case-study.md): the worked example behind that argument.
- [From Dune dashboard to DMs: turning analytics into action](https://walletlink.social/blog/dune-to-dms.md): the step after the query.
- [Web3 marketing in 2025: from spray-and-pray to identity-first](https://walletlink.social/blog/web3-marketing-2025.md): the category argument.
- [Wallets are the new social profiles: why Web3 identity changes everything](https://walletlink.social/blog/wallet-identity.md): the premise, stated plainly.
- [The future of wallet identity: what comes after 22%](https://walletlink.social/blog/future-of-wallet-identity.md): where coverage can honestly go.
- [walletlink.social vs Addressable: a practical comparison](https://walletlink.social/blog/walletlink-vs-addressable.md): the long-form version of the comparison page.
- [walletlink.social vs Blaze: comparison guide](https://walletlink.social/blog/walletlink-vs-blaze.md): same, for Blaze.
- [walletlink.social vs Cookie.fun: which tool fits your workflow?](https://walletlink.social/blog/walletlink-vs-cookie.md): about Cookie.fun, the attention-analytics product, which is a different company from Cookie3.
- [walletlink.social now supports Farcaster: 3x more wallet matches](https://walletlink.social/blog/farcaster-integration.md): the release that made Farcaster the deepest coverage.

## Who runs it

walletlink.social is operated by Starl3xx Labs LLC. The application is open source.

- [Source code](https://github.com/starl3xx/wallet-to-social): the repository behind the site and the API.
- [Changelog](https://github.com/starl3xx/wallet-to-social/blob/main/CHANGELOG.md): what shipped, and when.
- [Security policy](https://github.com/starl3xx/wallet-to-social/security/policy): how to report a vulnerability privately. The same contacts are in https://walletlink.social/.well-known/security.txt.

## Optional

- [X](https://x.com/walletlinkETH): product updates as @walletlinkETH.
- [Farcaster](https://farcaster.xyz/walletlink): the same, on the protocol the index covers completely.
- [Support](mailto:help@walletlink.social): help@walletlink.social. A person reads it.