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
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.
Decision
Policy engine
Destination rules, caps, budgets, approval threshold, emergency stop.
Signature
Shared key
Two shares. Keyban co-signs only the exact payment that was approved.
Blockchain
Smart account
Holds the funds and checks the signature against its registered signers.
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 leaks | What the attacker can do | What to do |
|---|---|---|
| The API key alone | Read 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 alone | Nothing 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 configuration | What 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 login | What 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 connection | The 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:
| Right | What it allows | Who holds it |
|---|---|---|
update | Edit the spending policy and the destination rules of a wallet or an application, and assign operators. | Owner and Admin. |
operate | Get 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. |
spend | Ask 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>.jsonby 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.jsonfile 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.
Related
- Security model: what the design defends against, and what it does not cover.
- Spending policy: every field Keyban checks before it co-signs.
- Operators and roles: assigning the people who run a wallet.
- Refusal reasons: every
policy/…reason.