Connect an agent, not a person
A remote MCP server at one URL. 8 tools over the same handlers, the same key and the same credits as the REST API, so an agent can resolve a wallet to the accounts its owner published without a person reading a reference first.
https://walletlink.social/api/mcpStreamable HTTP. Listed in the MCP registry as social.walletlink/wallet-identity, verified by DNS. Discovery is anonymous: a client can connect and list the tools with no credential at all, so an agent can see what is on offer before anything is bought. Calling a tool needs one.
Two ways to present a credential
Both are stored the same way and both reach the same meter by the same path. Neither is cheaper than the other, and nothing about billing changes between them.
| OAuth | API key | |
|---|---|---|
| Set up | Sign in when first asked | Create a key, paste it into a config |
| Lives for | An hour, renewed automatically | Until you revoke it |
| Can buy credits | No, and the rail refuses it before any money moves | Yes, as a top-up onto its own account |
| Best for | A person using a client | A server you run, where no browser can sign in |
An OAuth connection can resolve wallets in both directions, run a background job and read the balance. It cannot see saved lookups, billing details or the account email, and it can never buy. A tool call arriving with no credential, or with a token that has expired, is refused with a 401 and a challenge rather than a tool error, so a client refreshes and retries instead of handing the model a failure to read out.
One config block
For a client that takes neither OAuth nor a one-click install. The key goes in an Authorization header, exactly as it does for the REST API.
{
"mcpServers": {
"walletlink": {
"type": "http",
"url": "https://walletlink.social/api/mcp",
"headers": {
"Authorization": "Bearer wts_live_YOUR_KEY"
}
}
}
}Replace the placeholder with a key from the account menu. A key is shown exactly once, so the install links that carry a live key are offered on the screen that creates it and nowhere else.
The 8 tools, and what each costs
Every tool states its own cost in its own description, because an agent that cannot see the price cannot spend responsibly.
| Tool | Answers | Match credits |
|---|---|---|
| walletlink_resolve_wallets | Who is behind these addresses? | One credit per address that resolves |
| walletlink_estimate_list | What would resolving this list cost? | Free on the match meter |
| walletlink_submit_job | Run a long list, or re-check the misses against live sources | One credit per address that resolves, at completion |
| walletlink_job_status | How is that job doing, and what did it find? | Free on both meters |
| walletlink_wallets_by_x_handle | Which wallets belong to this X account? | One credit per wallet returned |
| walletlink_wallets_by_farcaster_username | Which wallets belong to this Farcaster account? | One credit per wallet returned |
| walletlink_index_coverage | How much of the index carries each identity? | Free on both meters |
| walletlink_account_balance | What is left on this key? | Free on both meters |
Resolving takes a list. Up to 50 addresses per call on the default plan; a live Scale pack raises the ceiling to 200 and Index to 1000, and the API refuses anything over your own ceiling, naming it. Billing is per address, not per identity: an address carrying both an X handle and a Farcaster account costs one credit.
The reverse direction is the expensive one. One page holds up to 100 wallets and each one is a match, so a single widely held handle can spend the whole free allowance of 100 matches per 30 days in one call. Read the balance first; that read is free.
A job goes deeper than a resolve. It resolves addresses the index has not checked against live sources, so it finds identities the resolve tool reports as never seen. One job runs per account at a time, a submission is capped at 10 times the match balance, and the matches are billed when the job completes. A job that fails is never billed.
Estimate before you spend. The dry run returns counts only, never identities: how many addresses are in the index, how many were checked and found bare, how many have never been seen, and the band a resolve would bill inside. Minimum 10 distinct addresses, free at any balance, and weighed against the rate window like the batch it previews.
Pacing. A batch call spends one request-unit per address of the per-minute window, and a full batch fills most of a minute on every plan: the default plan gives 60 units per minute and 50-address batches, and a live Scale or Index pack raises both. Pace multi-batch runs a minute apart and read the reset time from the quota.
A retry is a second purchase. Duplicates are removed inside one call, never across calls, and a tool call has nowhere to carry an idempotency key; the tools declare that honestly so a framework does not retry freely on a timeout. Before resending a call that may have gone through, read the balance instead of guessing.
At zero balance. 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. So a drained agent can always read its own meter and collect a job it already paid for, and that zero reading is the signal to buy again.
Paying with USDC, no account
An agent holding a wallet can buy its own credits. No card, no email, no sign-up.
POST https://walletlink.social/api/x402/buyPost with no payment and it answers 402 with a challenge describing what to pay. Pay $1.00 in USDC on Base and the response carries a fresh API key with 12 match credits behind it, which is roughly 51 resolvable addresses at our measured rate, or one full batch call. Any x402 client signs and reposts for you.
One settlement can buy 1 to 25 packs at linear price, so an agent with a real list stops paying a signature per pack. A buy that carries a valid key in the Authorization header is a top-up instead: the credits land on that key’s account and no second key is minted, which is how an agent recovers from a refusal mid-session without a new credential to manage. Every 10th settled purchase from the same wallet grants one bonus pack.
The key is shown once and stored only as a hash, so nobody can produce it again, including us. If it is lost, sign a challenge with the wallet that paid and a new key is issued against the same credits: the credits belong to the account, not to the key. They are the same credits a card buys, metered the same way, and they last 12 months.
What comes back
Not the raw record. The forty-odd fields per wallet are trimmed to the identity, whether the owner attested it, and whether the X handle still reaches anyone. 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 labelled so.
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. 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.
Every metered result carries the quota the call was admitted with, so an agent learns what it has left without spending a second call to ask. A refusal carries it too: the 402 reports the balance and the 429 reports the window and its reset.
Questions an agent operator asks
- How do I connect an AI agent to walletlink.social?
- Add https://walletlink.social/api/mcp to any MCP client. A client that supports OAuth needs nothing else: the first tool call opens a consent screen, you approve, and the call continues where it left off. A client that does not takes an Authorization header carrying a walletlink.social API key, self-serve from the account menu for any account holding credits. Tool discovery needs no credential at all, so an agent can list what is on offer before anything is bought.
- Can an agent pay without an account?
- Yes. POST to https://walletlink.social/api/x402/buy with no payment 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: no card, no email, no account. One settlement can buy up to 25 packs at linear price, and the credits are the same ones a card buys, metered the same way.
- What does each tool cost?
- 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. Resolving bills one credit per address that resolves. A reverse lookup bills one per wallet returned, which makes it the expensive direction. The estimate, the coverage read, the balance read and the job poll are free on both meters. 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.
- What can an OAuth connection reach?
- It can resolve wallets in both directions, submit a background job and read the credit balance. It cannot see saved lookups, billing details or the account email, and it cannot buy credits or change anything about the account. Access is a token that lasts an hour and renews itself, and disconnecting takes effect on the next call rather than at the end of the hour.
- What happens when an agent runs out of credits?
- The metered tools refuse with NO_CREDITS, and the refusal names both purchase paths rather than leaving an autonomous caller at a dead end. The free tools keep answering, so a drained agent can still read its own meter and collect a job it already paid for. An agent holding a wallet can also top up mid-session: a buy that presents the key it is already using puts the credits on that key’s account and mints no second credential.
Where the detail lives
- MCP server reference: every client path, the full response shape, the error rules and the limits.
- Agent pack over x402: the payment challenge, quantity, top-ups and recovering a lost key.
- /llms.txt: the whole product in one file, written for a model rather than a reader.
- Pricing: what a human buys, on the same meter the tools spend.