---
name: keyban-agent-wallet-setup
description: Install a Keyban Agent Wallet on this machine for the agent you are, from the wallet id the Keyban dashboard gives. Use when the user says to set up a Keyban agent wallet, or pastes the dashboard's set up line. Operating the wallet afterwards is the keyban-agent-wallet skill.
---

# Set up a Keyban Agent Wallet

The user pasted a line like:

```
Set up https://docs.keyban.io/.well-known/agent-skills/keyban-agent-wallet-setup/SKILL.md for the wallet <walletId> on <api>
```

`<walletId>` is the wallet to install, `<api>` the Keyban API it lives on
(`prod` when the line names none). Do the steps in order, on the machine you run
on. An **agent** step is yours to run. A **human** step is one only the user
can do: say exactly what to do and wait for them. Where a step is both, run
its command yourself, then tell the user what to finish. Say as little as you
can: speak only when the user must act, or when a step fails.

Never ask for the wallet's configuration or any of its values in the
conversation: it holds the wallet's API key and a one-shot invite key. The steps
below fetch it with the user's own session, straight into a file only they can
read.

## 1. Node.js — agent

Run `node --version`. Version 20 or later is needed. Without it, install it the
way this system installs software (the OS package manager, or
https://nodejs.org), telling the user what you install before you do. The
install takes minutes: wait for it to finish before you run `node --version`
again.

## 2. Set the wallet up — agent, then human

Run it yourself, so that the user approves one command:

```bash
npx -y @keyban/cli@latest setup --api <api> --wallet-id <walletId> --client <client>
```

It logs in, unless a session kept from an earlier login still serves: the login
opens the browser on the Keyban login, or prints the link to open elsewhere on
a machine without a browser. It does not go on until the user has logged in:
run the command in the background, so you can read its output while it
waits. The browser opening is enough for the user: do not look for its window
yourself, you cannot see it. Pass them the link only if they say none opened.
Keep reading its output until it returns; do not ask the user to tell you
they logged in. `Logged in to <api> as <account>` means the
login succeeded: do not retry it. The session is kept in
`$XDG_CONFIG_HOME/keyban/admin-session.json` (`~/.config/keyban/…` by default),
readable by its owner alone.

It then writes the wallet's file, `$XDG_CONFIG_HOME/keyban/wallets/<walletId>.json`
(mode 600), and the wallet is now the one the CLI drives. It refuses to
overwrite another wallet already kept there, its client share would be lost:
then it stops before the registration; stop and tell the user.

Last, with [install-mcp](https://github.com/supermemoryai/install-mcp), it adds
the server under the name `agent-wallet` to the agent you are. The server needs
no environment: it reads the wallet's file.

The command reaches the network and writes outside the folder a sandbox lets
you write (the keyban configuration, then the agent's own, `~/.codex/config.toml`
for Codex): run it outside the sandbox. In Codex, run it with escalated permissions; Codex Desktop refuses
that in a conversation opened outside a project, so if it does, tell the user to
open one from a project folder and set the wallet up from there.

`<client>` is the agent you are, as install-mcp names it: `claude-code`,
`codex`, `cursor`, `vscode`, `gemini-cli`, `goose`, `zed`, `windsurf`, `cline`…
(its README lists them all). It knows neither OpenClaw nor Hermes: for them,
run `npx -y @keyban/cli@latest admin --api <api> login && npx -y
@keyban/cli@latest wallet import --api <api> --wallet-id <walletId>` instead,
then register the server their way:

| Agent | How |
|---|---|
| OpenClaw | `openclaw mcp set agent-wallet '{"command":"npx","args":["-y","@keyban/cli@latest","mcp"]}'` |
| Hermes | add the block below under `mcp_servers:` in `~/.hermes/config.yaml` |

```yaml
mcp_servers:
  agent-wallet:
    command: "npx"
    args: ["-y", "@keyban/cli@latest", "mcp"]
```

Keep the `@latest`: without it, npx reuses the copy it cached first, and a
restart never picks up a new release.

An agent that runs no MCP server can drive the wallet through the shell
instead: `npx -y @keyban/cli@latest wallet --help` lists one subcommand per
tool.

## 3. Hand back — agent

The wallet is installed, but this conversation cannot use it: its servers were
loaded before the registration. A new conversation (a new session, for an agent
run from a terminal) must ask "Wallet balance, name and address?", or "Credit,
name and address?" for a prepaid account.

If you can open one yourself, one the user sees and keeps using, open it now
with that prompt, before you say anything and before you end your turn: by
pasting the line, the user explicitly asked you for that new conversation, so
do not ask or wait for them. A session that runs hidden and only hands you its
answer does not count. Then tell them in a sentence that it is open.

Only if you cannot, tell the user in a sentence, with no file, command or
server name, that this conversation cannot use the wallet, and to open a new
one and ask that there. For a wallet, that first call activates it: it
generates the signing key, which takes a few seconds, and the dashboard waits
for it before moving on. A prepaid account has no key: it activates on its first
payment request. Do not send the user back to the dashboard instead: what comes
next happens in that new conversation.

Operating the wallet afterwards (funding, payments, approvals, missions) is the
`keyban-agent-wallet` skill: `agent-wallet:get_wallet_instructions`, or
https://docs.keyban.io/.well-known/agent-skills/keyban-agent-wallet/SKILL.md

## Hosted agents

An agent that a platform runs for the user (Amazon Bedrock AgentCore, a Claude
managed agent) does not install itself: whoever deploys it gives it the wallet's
file, as the dashboard hands it out for that platform. This skill is not for
them.
