Skip to main content

Agent wallet security

An agent wallet holds money that an agent spends on its own. This page explains what protects it: the layers a payment goes through, what each leaked credential gives an attacker, who can change what, and where the agent's key share lives. What the design defends against is in the Security model.

The layers a payment goes through​

  1. Identity

    • API key

      The agent's. Asks for payments for its own wallet and reads the organization's agent wallets, nothing else.

    • A person's sign-in

      Session or OAuth. Sets the limits and approves held payments. It cannot make the agent's wallet pay.

  2. Decision

    • Policy engine

      Destination rules, caps, budgets, approval threshold, emergency stop.

  3. Signature

    • Shared key

      Two shares. Keyban co-signs only the exact payment that was approved.

  4. Blockchain

    • Smart account

      Holds the funds and checks the signature against its registered signers.

A payment request carries the agent's API key. The people who set the limits and approve held payments act with their own sign-in, a session in the dashboard or an OAuth token, which cannot make the agent's wallet pay. The request is evaluated by Keyban's policy engine, co-signed by Keyban with the agent's key share only if approved, and checked by the wallet's smart account on the blockchain. The emergency stop, in the policy engine, refuses everything while the wallet is paused.

In short, for the agent to get a payment out, it needs a valid API key and a policy decision that approves it, and Keyban co-signs only after that decision. The limits and the approvals come from people, signed in with their own account.

API key​

Every request from the wallet MCP server to Keyban carries an API key. The key holds two rights on agent wallets: read and spend. It can ask Keyban to evaluate and sign payments for its own wallet only: the signer routes refuse a key bound to another wallet. Its read right is not narrowed to that wallet, though: it can read the agent wallets of the organization, and the spending of the whole application. It cannot edit the policy or the destination rules, approve a held payment, pause or resume the wallet, or add a signer. Those actions need the update or operate rights, and every operate action must be attributable to a person, so any API key is refused with 403.

A person's sign-in​

The people who set the limits and decide on held payments act with their own sign-in: a session in the dashboard, or an OAuth token when they use the admin tools from their assistant or from the Keyban CLI (keyban admin login). The token carries that person's role. With it they can change a wallet's policy, approve or decline a held payment, and pause or resume a wallet. It cannot ask for or sign a payment from an agent wallet: only the agent's API key holds the spend right. Granting a standing approval to a mission needs a session in the dashboard, and an OAuth token is refused.

On a machine where an agent runs, a person's sign-in is a risk. As soon as someone runs keyban admin login there, the Keyban MCP server serves the admin tools beside the wallet's, with that person's rights: the agent could then approve its own held payments or raise its own limits. Sign in only on your own machine. keyban admin logout deletes the tokens from the machine.

Policy engine​

Keyban evaluates every payment request on its own servers, before anything is signed: the organization's transaction quota, the emergency stop, the destination rules at organization, application and wallet level, the per-payment cap, the day, week and month budgets of the wallet, the monthly envelopes of its application and its organization, and the approval threshold. A payment above the threshold waits for a person to approve or decline it: it is never approved by default. The fields and the order of the checks are in Spending policy.

The decision is bound to the exact payment. When the agent then asks Keyban to co-sign, Keyban looks up the approved request whose hash matches what is being signed, checks the emergency stop again, and marks the approval as used in the same database transaction. A payload that was not evaluated is refused with policy/intent-not-found, and an approval can be signed once only: a second attempt is refused with policy/intent-already-consumed. The sign_message tool goes through the same check, so the agent cannot use it to sign an arbitrary message. A wallet without a policy is refused with policy/missing. Every reason is listed in Refusal reasons.

Shared key​

The agent's signing key is a two-party threshold key (FROST, RFC 9591, on secp256k1). One share is kept where the agent runs, the other by Keyban. The two shares are created together and the agent's complete private key never exists in one place, neither when it is created nor when it signs: the two sides run a short interactive protocol and combine partial signatures into one ordinary signature.

The agent cannot sign without being authenticated on Keyban, and Keyban only co-signs what the policy allows. Keyban reaches its share only for requests that carry the API key the share was created with. Stealing the agent's share therefore does not let anyone pay outside the policy. How a signer is enrolled and rotated is in What a leaked credential gives an attacker.

Smart account and relayer​

The funds are held by the wallet's smart account, an ERC-4337 contract. It holds no key: it verifies signatures itself against the signers registered on it, and answers other contracts that check a signature for it through ERC-1271, with the signature wrapped in an ERC-7739 envelope. Its address does not change when signers are added or removed.

A USDC transfer reaches the blockchain through Keyban's relayer, which pays the gas. The relayer goes through a relay hub contract: the wallet's relayed entry point accepts only a caller that holds the relay role (RELAY_HUB_ROLE), which Keyban grants only to the hub. The wallet then checks the signature against its signers and against a nonce that increases with every relayed call, so the relayer can deliver only what was signed, and each signature only once. An x402 payment takes a different route: the agent signs an authorization that the seller's payment facilitator submits, and the USDC contract checks that signature against the wallet. See x402 protocol.

Emergency stop​

The emergency stop pauses one wallet at once. A person with the operate right on the wallet sets it from the dashboard, or with the admin tool freeze_wallet of the Keyban MCP server, after keyban admin login, and every payment request from the wallet is then refused with policy/emergency-stop until someone resumes it. It is a flag in the policy, enforced by Keyban's policy engine, not a rule written on the blockchain. Keyban checks it again when it co-signs, so it also stops a payment that was approved but not yet signed.

What a leaked credential gives an attacker​

What leaksWhat the attacker can doWhat to do
The API key aloneRead the data of the organization's agent wallets and ask for payments for its own wallet. It cannot sign from the wallet without the key share. It can still obtain payments that Keyban signs itself, such as those the Keyban welcome offer pays, within the policy.Pause the wallet, then rotate the signer.
The key share aloneNothing on its own: every signature with the agent's key needs Keyban, and Keyban uses its share only for requests that carry the wallet's API key.Rotate the signer.
The API key and the share, or the whole configurationWhat the agent can do: spend inside the policy until the wallet is paused or the signer deleted.Pause the wallet, then rotate the signer.
A person's OAuth sign-in, from keyban admin loginWhat that person may do: change the limits, approve or decline held payments, pause or resume wallets. It cannot ask for or sign a payment from an agent wallet.Run keyban admin logout on that machine. It deletes the tokens there, not a copy already taken, so check the payments approved in that person's name.
The configuration before the agent's first connectionThe configuration holds the invitation (KEYBAN_INVITE_KEY) that registers the first key on the wallet. Whoever uses it first registers their own key.Give the signer a fresh invitation, which cancels the old one, or delete the signer.

To rotate a signer, add a new one, install it on the agent and let it connect once, then delete the old one. Deleting a signer removes it from the smart account on the blockchain and revokes its API key, and the wallet address does not change. Adding a signer needs the operate right, and deleting one needs the delete right, which Owner and Admin hold.

Who can change what​

The person who decides the limits is not the person who runs the agent, and neither is the agent. Three rights apply to an agent wallet:

RightWhat it allowsWho holds it
updateEdit the spending policy and the destination rules of a wallet or an application, and assign operators.Owner and Admin.
operateGet its MCP configuration, add a signer, approve or decline held payments, pause and resume the wallet, and ask for a top-up.Owner and Admin on every wallet. Editor, shown as "Operator" in the dashboard, only on the wallets they are assigned to.
spendAsk Keyban to evaluate and sign a payment.The agent's API key, and nothing else.

Every operate action must come from a person, through a signed-in dashboard session or a person's OAuth sign-in, so an API key is refused even when it belongs to an Owner. The agent's own key never holds update or operate: it cannot raise its limits, resume its own wallet or approve its own payment. An operator receives the wallet's MCP configuration, which holds what the agent needs to run, so assign operators with care. The destination rules at organization level need the organization settings right. See Operators and roles.

Where the agent's share lives​

The share is created at the first wallet tool call that needs the account, and the install path decides where it is kept:

  • On a machine you control (Claude Desktop, Claude Code, ChatGPT or Codex, OpenClaw, Hermes, other MCP clients): in the wallet's file, $XDG_CONFIG_HOME/keyban/wallets/<wallet id>.json, which is ~/.config/keyban/wallets/<wallet id>.json by default. The file is readable by its owner only (mode 600).
  • On a hosted agent (a Claude managed agent, Amazon Bedrock AgentCore): the dashboard wizard generates the share in your browser, once, and puts it in what you hand to the platform, a mounted wallet.json file or one pasted value. The share cannot be exported again. See Compatible agents.

The file's permissions protect the share at the level of your user account, not of a program: any program running as you can read the share and the API key from the wallet's file, or start the wallet MCP server itself. Such a program is bound exactly like the agent, because Keyban co-signs every signature and evaluates the policy first, but it can spend inside that policy. Treat the account that holds the file like one that holds an SSH key, and treat a hosted agent's wallet.json or pasted value like a password, since it carries the share.