---
name: keyban-agent-wallet
description: Operate a Keyban Agent Wallet, an AI agent's own USDC wallet whose spending policy is enforced server-side, through the local agent wallet MCP. Use when the user wants an agent to pay x402 APIs, transfer USDC, check its balance or spending, or when a payment waits for a human or is refused by the policy. Creating and configuring the wallet is the keyban-admin skill.
---

# Keyban Agent Wallet

A Keyban Agent Wallet is a smart account owned by one AI agent. It holds USDC and
pays x402 APIs or addresses. Keyban checks every spend at signature time against
the policy the user set: per-payment cap, daily, weekly and monthly budgets,
destination rules, and a threshold above which a human must approve. The key is
a threshold key: one share stays on the machine that runs the agent, the other at
Keyban, and neither side can sign alone.

## Two MCP servers, two roles

| | Keyban admin MCP | Agent wallet MCP |
|---|---|---|
| Acts as | the signed-in user (OAuth) | the agent, through one wallet |
| Runs | remote, `https://mcp.keyban.io/mcp` | local, `npx -y @keyban/cli@latest mcp` |
| Default server name | `keyban` | `agent-wallet` |
| Does | organization, applications, agent wallets, destination rules, x402 catalogue, quotas, billing | balance, spending, USDC transfers, x402 payments, approval waits |
| Does not | spend, install the wallet's signer, approve payments, edit an existing wallet's spending caps | create or configure wallets, approve its own payments |
| Guide | `keyban:get_instructions`, the `keyban-admin` skill | `agent-wallet:get_instructions`, this skill |

Tools are written `server:tool` with the default server names. If the user gave
the servers other names, use theirs.

The policy is the user's decision. Never use the admin MCP to get around a
refusal from the agent wallet MCP.

## Before the wallet exists

The wallet is created and configured through the Keyban admin MCP, and its MCP
configuration is installed from the dashboard. That part of the journey, from
the account to this server installed, is the `keyban-admin` skill.

1. The user needs a Keyban account (there is a free plan at
   https://www.keyban.io/en/pricing/agent-wallet/) and the admin MCP connected
   to the client: https://docs.keyban.io/reference/set-up-mcp-server
2. Then call `keyban:get_instructions` and follow it. It ends with this server
   installed and `agent-wallet:get_account_info` answering.

If this server lists `setup_instructions`, it has no wallet to drive yet: call
it, and send the user to the dashboard for the configuration. Never ask for that
configuration or any of its values in the conversation: it holds the wallet's
API key and a one-shot invite key.

## Fund the wallet — human

Not needed for a payment the Keyban welcome offer covers (see below).

USDC on the wallet's network, sent to the address from
`agent-wallet:get_account_info`. The wallet page in the dashboard also offers a
card top-up (Base mainnet only, 5 to 999 EUR per purchase) and a top-up request
to a teammate. Test USDC: https://faucet.circle.com/

## Operate the wallet

- Read: `agent-wallet:balance` (report the fiat value first),
  `agent-wallet:expense_stats`, `agent-wallet:list_expense_transactions`.
- A new organization's first payments may be covered by the Keyban welcome
  offer, shown by `agent-wallet:balance` and `agent-wallet:get_account_info`.
  On first use, report it with the balance, and do not say the wallet needs
  funding while the offer has an amount left that covers the payment. The
  offer pays a payment only when its whole price fits in what is left, so a
  wallet holding 0 USDC can still pay that much; a costlier payment is paid
  entirely from the wallet, never split. When the offer can no longer cover a
  payment, `agent-wallet:x402_pay` pays from the wallet on its own; nothing to
  do.
- Pay an x402 API:
  1. find a service with `agent-wallet:discover_x402_services`;
  2. check its price **and its parameters** with `agent-wallet:x402_info`,
     using the HTTP method the service serves; for a variable price, probe
     with the same method, query and body you will pay with;
  3. pay and fetch with `agent-wallet:x402_pay`, same URL, method and body.

  Skip a provider that discovery marks `payable: no` or whose `x402_info`
  prints `⚠ Not payable`: its offer is one this wallet cannot settle.

  Replace each `{…}` segment of a URL with a real value before probing or
  paying.

  A service listed "via" a gateway (e.g. Orthogonal) is paid the same way: the
  gateway collects the payment and calls the provider for you.
- Send USDC: `agent-wallet:transfer_usdc`, amount in USDC (`"1.5"`), not in
  base units.

The policy is the user's authorization: do not ask the user to confirm a payment
the policy allows.

## When a human must approve

A payment above the approval threshold is held, and the tool fails with an
`intentId`.

1. Tell the user the amount, the recipient and the deadline, with the link
   `https://admin.keyban.io/app/<applicationId>/inbox?intent=<intentId>`.
   Approval needs the user's own session: no tool can approve.
2. In the same turn, call `agent-wallet:wait_for_intent`, and call it again
   each time it comes back still waiting, until the intent is decided or expires.
3. Once approved, retry the same call with that `intentId`. Never start a new
   payment for the same purchase: it creates a second intent.
4. To withdraw a pending request, call `agent-wallet:cancel_intent`.

## When the policy refuses

A refusal carries `policy/…` reasons. Report the reason in plain words and drop
that payment.

| Reason | Meaning | What the user can do |
|---|---|---|
| `policy/amount-exceeded` | above the per-payment cap | raise the cap on the wallet page |
| `policy/budget-day-exceeded`, `-week-`, `-month-` | the period's budget is used | wait, or raise the budget on the wallet page |
| `policy/recipient-…`, `policy/domain-…` | destination not allowed at some scope | change a destination rule, through the admin MCP only if the user asks |
| `policy/intent-in-flight` | an earlier transfer is still pending | wait for it, or cancel it with `agent-wallet:cancel_intent` |
| `policy/emergency-stop` | the wallet is paused | resume it on the wallet page |
| `policy/transaction-quota-reached` | the organization's monthly transaction quota (its plan) is used up — for every wallet of the organization, until the 1st of next month (UTC) | do not retry; ask an organization admin to upgrade the plan or allow billed overage in Billing → Usage |
| `policy/missing` | the wallet has no policy (403 at signing) | ask the user to open the wallet page; do not retry |
| `policy/x402-no-exact-accept` | the seller only offers an x402 payment scheme the wallet cannot settle yet (e.g. `upto`) — a current limit of the wallet, not a budget problem | do not retry; pick another provider and tell the user |
| `policy/x402-…` | the seller's x402 offer cannot be paid (unreachable, malformed, wrong asset or chain, above `maxAmount`) | pick another provider |

Never split a payment into smaller ones to stay under a cap or the approval
threshold, and never route a payment around a destination rule.

## Troubleshooting

- The agent wallet MCP shows `setup_instructions`: it is not configured. Call
  it, then go back to the admin skill's installation step.
- `KEYBAN_NETWORK` accepts `BaseMainnet`, `BaseSepolia`, `XdcMainnet` and
  `XdcApothem`, case-sensitive.
- `agent-wallet:api_status` checks that the Keyban API answers.
- Running the agent wallet MCP on Amazon Bedrock AgentCore: see the package
  README.
- The signer's share or API key may have leaked: any program running as the
  user can read them. Rotate with the admin MCP: add a new signer, set it up,
  then delete the old one; that revokes both, and the address stays.

## Links

- Admin MCP guide: https://docs.keyban.io/.well-known/agent-skills/keyban-admin/SKILL.md
- Agent wallet overview: https://docs.keyban.io/solutions/agent-wallet/introduction
- Security model: https://docs.keyban.io/solutions/agent-wallet/security
- Connect an assistant to the admin MCP: https://docs.keyban.io/reference/set-up-mcp-server
- Admin MCP tools: https://docs.keyban.io/reference/mcp-tools
- Pricing: https://www.keyban.io/en/pricing/agent-wallet/
- Agent wallet MCP package: https://www.npmjs.com/package/@keyban/cli