> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletlink.social/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Five tools that let an agent resolve wallets to social identities, over the same API and the same balance.

An agent can call walletlink.social directly, without a human first reading this
reference. The server is remote, needs no OAuth, and authenticates with the same
key the REST API uses.

```
https://walletlink.social/api/mcp
```

## Connect

### One click, from the app

When you create an API key, the modal offers **Add to Cursor** and **Copy
Claude Code command**, both already carrying that key. That is the shortest
path, and it is only offered there: a key is shown exactly once, so a link
published on this page could only carry a placeholder, and a placeholder
installs a server that fails on first use.

### Claude Code, one line

```bash theme={null}
claude mcp add --transport http walletlink https://walletlink.social/api/mcp \
  --header "Authorization: Bearer wts_live_YOUR_KEY"
```

That installs it for the current project. Add `-s user` to make it available in
every project instead.

### By hand

Add the server to your client’s config. The key goes in an `Authorization`
header, exactly as it does for the REST API.

<CodeGroup>
  ```json Claude Code / Claude Desktop theme={null}
  {
    "mcpServers": {
      "walletlink": {
        "type": "http",
        "url": "https://walletlink.social/api/mcp",
        "headers": {
          "Authorization": "Bearer wts_live_YOUR_KEY"
        }
      }
    }
  }
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "walletlink": {
        "url": "https://walletlink.social/api/mcp",
        "headers": {
          "Authorization": "Bearer wts_live_YOUR_KEY"
        }
      }
    }
  }
  ```
</CodeGroup>

Keys are self-serve from the account menu for any account holding credits.

<Note>
  Discovery works without a key. A client can connect and list the tools with no
  `Authorization` header at all, so you can see what is on offer before buying
  anything. Calling a tool needs a key.
</Note>

## The five tools

| Tool                                       | Answers                                      | Match credits                    |
| ------------------------------------------ | -------------------------------------------- | -------------------------------- |
| `walletlink_resolve_wallets`               | Who is behind these addresses?               | 1 per address that resolves      |
| `walletlink_wallets_by_x_handle`           | Which wallets belong to this X account?      | 1 per wallet returned, up to 100 |
| `walletlink_wallets_by_farcaster_username` | Which wallets belong to this Farcaster user? | 1 per wallet returned, up to 100 |
| `walletlink_index_coverage`                | How much of the index carries each identity? | 0                                |
| `walletlink_account_balance`               | What is left on this key?                    | 0                                |

Six endpoints become five tools because the single and batch lookups answer the
same question at two sizes and bill by the same rule.
`walletlink_resolve_wallets` takes 1 to 50 addresses and picks the endpoint for
you.

## It is the same meter

The tools carry your key into the same handlers the REST API uses, so nothing
about billing changes. Misses are free, a match means an X handle or a Farcaster
account, and an ENS name on its own is returned and not charged. See
[credits](/api-reference/introduction#credits).

Two consequences worth knowing before you point an agent at it:

**A reverse lookup can spend 100 credits in one call.** A page holds up to 100
wallets and each one is a match. The free allowance is 100 matches per rolling
30 days, so a single widely held handle can spend all of it at once. There is no
page-size parameter. Have the agent call `walletlink_account_balance` first,
which is free.

**Nothing is reserved.** The balance is checked, not held, so a call that
resolves more than you have left is allowed to finish and the next one fails
with no credits. That is the same behaviour the REST API and the app have.

## What the tools return

Not the raw API record. The 40-odd fields per wallet are trimmed to the identity,
whether the owner attested it, and whether the X handle still reaches anyone,
which is the field no competing source publishes.

```json theme={null}
{
  "requested": 2,
  "billed_matches": 1,
  "results": [
    {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "ens": "vitalik.eth",
      "x": {
        "handle": "vitalikbuterin",
        "url": "https://x.com/vitalikbuterin",
        "attested": true,
        "reaches_someone": true,
        "reachability": "live"
      },
      "evidence": ["onchain", "farcaster"]
    },
    { "address": "0x0000000000000000000000000000000000000001", "found": false }
  ]
}
```

`reaches_someone` and `reachability` are **omitted** when we have not resolved
the handle. Absent is not false: see
[when a handle stops being true](/concepts/data-quality#when-a-handle-stops-being-true).

## The REST surface

Everything these tools do is also available over the REST API, described in
OpenAPI 3.1 at
[`docs.walletlink.social/openapi.yaml`](https://docs.walletlink.social/openapi.yaml)
if you would rather generate a client than install a server.

## Errors

A failed call comes back as a tool error with a readable message, never as a
transport failure, so the session survives and the agent can tell you what went
wrong. Out of credits reads as "No credits left. Buy a pack to continue."

## Limits

Tool calls are limited per key, on the same three windows as the REST API. See
[rate limits](/api-reference/rate-limits).

Everything except a tool call is limited per IP address, at 120 requests an
hour. That covers `initialize`, `tools/list` and every other method, all of
which answer without reaching the API and so are not metered against any key.

Tool calls are not subject to it. They are metered against your key instead, on
the three windows above.