@keyban/agent-wallet-mcp

Give an AI agent its own blockchain wallet: balances, USDC transfers and x402 payments, under a spending policy the agent cannot change.

Registry name: io.keyban.prod.mcp/agent-wallet.

The server runs locally over stdio, next to your MCP client. It holds one share of a FROST threshold key in your OS keyring; Keyban holds the other. No single side can move funds alone, and the model never sees either share or your API key.

You need a Keyban wallet first

This server drives a wallet Keyban provisions. It does not create one, and it has nothing to drive without one — installing the package on its own gets you a server offering a single setup_instructions tool, which points back here. The threshold key is the reason: one share lives here, the other lives with us, so there is a Keyban side to every wallet by construction and no configuration can replace it.

So the order is:

1. Get a Keyban account at https://keyban.io.
2. Create an agent wallet in the admin app. It provisions the wallet, its API key, and a one-shot invite key that authorises this client as a signer.
3. Take the configuration it hands you — either the environment block for the table below, or a ready-to-install .mcpb bundle with the values already in it.
4. Then install, with those values in the environment.

Install

Once you have the credentials from step 3:

npx -y @keyban/agent-wallet-mcp

With Claude Code:

claude mcp add agent-wallet \
  -e KEYBAN_API_KEY=… \
  -e KEYBAN_APP_ID=… \
  -e KEYBAN_INVITE_KEY=0x… \
  -e KEYBAN_WALLET_ADDRESS=0x… \
  -e KEYBAN_NETWORK=… \
  -- npx -y @keyban/agent-wallet-mcp

On first boot the server runs a key generation, keeps its share in your OS keyring, and registers itself on chain as a signer of that wallet using the invite key. That happens once per machine; the invite key is spent by it.

Configuration

The five required values all come from step 2 — none of them is something you can pick yourself.

| Variable | Required | What it is | |---|---|---| | KEYBAN_API_KEY | yes | API key of the application the wallet belongs to. Never exposed to the model. | | KEYBAN_APP_ID | yes | Identifier of the Keyban application. | | KEYBAN_INVITE_KEY | yes | One-shot ECDSA private key authorizing this client's first-boot registration as a signer. | | KEYBAN_WALLET_ADDRESS | yes | Address of the account this server drives. | | KEYBAN_NETWORK | yes | Network the wallet operates on, e.g. base or xdc. | | KEYBAN_BASE_URL | no | Backend base URL, or one of dev, testing, staging, prod, sandbox. Defaults to https://api.prod.keyban.io. | | KEYBAN_DKG_BLOB | no | Pre-generated signer share, base64 JSON. For runtimes with no OS keyring; it does not replace the invite key. | | MCP_LOG_FILE | no | Path the server writes its log to. | | MCP_LOG_LEVEL | no | debug, info, warn or error. Defaults to info. |

Tools

Read-only:

| Tool | What it does | |---|---| | api_status | Check Keyban API status | | get_account_info | Get wallet account info | | balance | Check wallet balance | | list_expense_transactions | List wallet transactions | | expense_stats | Get spending statistics | | wait_for_intent | Wait for approval decisions | | x402_info | Inspect the x402 price of a URL | | discover_x402_services | Search the x402 service directory |

Writing:

| Tool | What it does | |---|---| | sign_message | Sign a message | | cancel_intent | Cancel a pending payment intent | | transfer_usdc | Transfer USDC — moves funds | | x402_pay | Pay for an x402 resource — moves funds |

Every tool carries a title and the applicable readOnlyHint or destructiveHint, so a client can tell the two groups apart before calling anything.

Spending policy

Transfers and x402 payments are checked against the wallet's policy on the Keyban side. A call the policy will not clear on its own does not fail silently: it comes back naming a payment intent that needs a human decision. wait_for_intent blocks until the owner approves or declines, and the agent retries once it is approved. The policy lives with the wallet, not with this process, so editing this server's configuration cannot widen it.

Documentation

https://docs.keyban.io/

License

Apache-2.0. See LICENSE.