---
name: keyban-agent-wallet-integrate
description: Integrate Keyban Wallet for Agents into the agents the user builds and runs, from their repository - check that it fits, propose the environments and what each wallet stands for, create the wallets with the Keyban CLI and wire each runtime (Claude Platform, LangChain, CrewAI, Amazon Bedrock AgentCore or another). Use when the user asks to integrate Keyban wallets into their agents, to give wallets to several agents, or to replace the paid APIs or subscriptions their agents use with x402 payments. Installing one wallet for yourself is the keyban-agent-wallet-setup skill, and operating a wallet is the keyban-agent-wallet skill.
---

# Integrate Keyban agent wallets into the user's agents

You are the user's coding agent, in their repository. They want the agents they
build and run, on a platform and with no person in the conversation, to pay
their services through Keyban wallets. There may be one agent or many. You
integrate: you never pay, and you never use a wallet meant for one of their
agents: you create its file and hand it to the runtime.

Work in this order, and stop where a step says so. A step marked **human** is
one only the user can do: say exactly what to do and wait.

The page for people, with the same path, is
https://docs.keyban.io/solutions/agent-wallet/integrate-your-agents.md

## 1. Check that it fits — create nothing

Read the repository, then report to the user before creating anything.

- **The agents.** Which agents there are, the framework or platform they run on
  (Claude Platform managed agents, LangChain, CrewAI, Amazon Bedrock AgentCore,
  a container you run…), how many instances or parallel sessions each one has,
  and where their secrets live today.
- **The runtime.** Each agent must either start an MCP server over stdio
  (`npx -y @keyban/cli@latest mcp`) or run shell commands (`keyban wallet …`),
  with Node.js 20 or later and network access to the Keyban API. Say which
  agents cannot, and why.
- **The paid APIs.** Find what the agents pay for today: API keys in the
  configuration, SDK clients, HTTP calls to paid providers, subscriptions the
  user mentions. For each one, look for an x402 service that sells the same
  thing:
  - `npx -y @keyban/cli@latest admin list-x402-services` searches the Keyban
    catalog (it needs the user signed in, step 3);
  - if a Keyban wallet is installed on this machine, `keyban wallet
    discover-x402-services` searches the same catalog and `keyban wallet
    x402-info` reads a service's price and parameters without paying;
  - a provider marked not payable cannot be settled by a Keyban wallet.
- **The cost.** x402 charges per call. Estimate the monthly cost at the
  agents' volume and compare it with what the user pays today. A mission trial,
  run later from a wallet, measures it for real.
- **The network.** x402 payments work on Base mainnet and XDC mainnet. Each
  Keyban application runs on one network.
- **The plan.** The plan caps the number of applications and includes a number
  of wallets: https://docs.keyban.io/solutions/agent-wallet/features/billing.md

Report in a few lines: a table of each paid API with its x402 equivalent, price
and whether it is payable, the agents that fit and those that do not, the
estimated cost, and what blocks. **Stop and wait for the user.**

## 2. Propose the design — human decides

Propose, then wait for the user's agreement on each point:

- **What a wallet stands for.** The user decides; never pick for them. Present
  the three options with what follows:
  - one wallet per **agent** (an agent on Claude Platform, an agent class in
    LangChain or CrewAI code): every session or instance shares its wallet and
    budget, even in parallel; each agent can be paused and followed;
  - one wallet per **team or cost centre**: several agents spend from one
    budget; few wallets; pausing stops every agent of the team, and the
    spending does not tell the agents apart;
  - one wallet per **end customer**: spending and limits per customer, so they
    can be billed back; as many wallets as customers.
  Never one wallet per session or per run: a session is short-lived, a wallet
  keeps its key share and counts against the plan. Count the wallets against
  the plan.
- **Environments.** One Keyban application per environment (for example
  `dev`, `staging`, `prod`), each with its monthly budget and destination
  rules; small budgets outside `prod`; `prod` limited to the services
  validated in step 1. All run on a mainnet network: tests pay real services
  with real money.
- **Each wallet's policy.** Per-payment cap, daily, weekly and monthly budgets,
  and an approval threshold high enough that routine payments pass on their
  own: above it, a payment waits for a person in the dashboard.
- **Missions.** Which repeatable tasks become missions: tuned and published
  from one wallet, shared with the application or the organization, then run
  by the agents' wallets. A wallet whose policy requires a mission pays only
  inside a run.
- **Funding.** Who funds the wallets and how: by card in the dashboard, by
  sending USDC, or from the organization's multisig treasury, which refills up
  to 20 wallets in one signed batch (Growth plan and above).

## 3. Write the provisioning script

Write it in the repository, for the user to review, then run it with them.

- **Human, then agent:** run `npx -y @keyban/cli@latest admin login` in the
  background: it opens the browser or prints a link. The user signs in with an
  Owner or Admin account; you act with their rights from then on.
- One application per environment: `keyban admin list-applications` first,
  then `keyban admin create-application --name <env>` for the missing ones.
- Each application's budget and destination rules:
  `keyban admin set-application-shared-budget` and
  `keyban admin set-application-destination-rule`.
- Each wallet, its policy and its key share in one file:

  ```bash
  KEYBAN_WALLET_PATH=<secret path>/<label>.json \
    npx -y @keyban/cli@latest admin new-wallet \
      --application-name <env> --label <label> --network BaseMainnet \
      --policy '<policy JSON>' --share
  ```

  The file is the whole wallet: its API key, its configuration and its key
  share. The first wallet of an application fixes its network.
- Read `npx -y @keyban/cli@latest admin <command> --help` for each command's
  fields and amount encoding. Never guess a field.
- Make the script safe to run again: skip a wallet whose file already exists.
  Never pass `--force`: overwriting a wallet file loses its key share.
- A budget above what its parent allows is refused with a preview of the
  raises it needs: show it to the user, and change nothing without their
  agreement.

## 4. Keep the wallet files secret

- Put each file in the user's secret store (one secret per wallet), then
  delete the local copy. Add the local directory to `.gitignore` before the
  first run.
- Never commit a wallet file, bake it into an image, print it, paste it in a
  prompt, a log, a ticket or a conversation.
- A key share is generated once and cannot be exported again: a lost file means
  a new wallet. A leaked file: the user pauses the wallet first (emergency stop
  in the dashboard), then it is replaced.

## 5. Wire each runtime

| Runtime | What to wire |
| --- | --- |
| Claude managed agent (Claude Platform) | Mount the wallet file in the agent at `/uploads/wallet.json`. Its environment needs the npm package `@keyban/cli` and network access to the Keyban API. Its system prompt starts with: `You hold a wallet through the keyban CLI: export KEYBAN_WALLET_PATH=/mnt/session/uploads/wallet.json before each keyban command, then read keyban wallet get-wallet-instructions and follow it.` |
| LangChain, CrewAI or any framework with an MCP client | Start the stdio server `npx -y @keyban/cli@latest mcp` with the framework's own MCP client, one server per agent, with `KEYBAN_WALLET_PATH` (the file mounted from the secret store) or `KEYBAN_CONFIG` (the file encoded in base64) in its environment. |
| Environment variables only (Amazon Bedrock AgentCore, a serverless container) | `KEYBAN_CONFIG`, the wallet file encoded in base64. |
| A shell and no MCP client | The same variables, with `keyban wallet <tool>` commands. |

- Keep `@latest`, so a restart picks up new releases.
- Each agent learns the wallet from the `get_wallet_instructions` tool (or
  `keyban wallet get-wallet-instructions`): have it read it at start, and let
  it follow the operating skill.
- Remove the paid API keys the x402 services replace only once the user has
  seen the agents pay.
- Each of the user's agents holds its wallet and nothing else: never an admin session,
  never another agent's wallet.

## 6. Check, then hand back

- In a test environment, run one agent: it reads its balance, then pays one
  service within its limits. Ask the user to check the payment in the
  dashboard's **Expenses** for that application.
- Hand back in a few lines: the applications and their budgets, the wallets
  created (labels, not files), where their files are kept, what still needs a
  person (funding, the Inbox, the budget e-mails), and the paid APIs left in
  place.

## Links

- Integration guide: https://docs.keyban.io/solutions/agent-wallet/integrate-your-agents.md
- How it works: https://docs.keyban.io/solutions/agent-wallet/how-it-works.md
- Spending policy: https://docs.keyban.io/solutions/agent-wallet/concepts/policy.md
- Missions: https://docs.keyban.io/solutions/agent-wallet/concepts/missions.md
- Multisig treasury: https://docs.keyban.io/solutions/agent-wallet/concepts/treasury.md
- Plans and quotas: https://docs.keyban.io/solutions/agent-wallet/features/billing.md
- Security: https://docs.keyban.io/solutions/agent-wallet/security.md
- Admin tools (each is a `keyban admin` command): https://docs.keyban.io/solutions/agent-wallet/reference/admin-mcp-tools.md
- Operate a wallet (the skill of the user's agents): https://docs.keyban.io/.well-known/agent-skills/keyban-agent-wallet/SKILL.md
- Install one wallet for yourself: https://docs.keyban.io/.well-known/agent-skills/keyban-agent-wallet-setup/SKILL.md
