@keyban/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Keyban
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# @keyban/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give an AI agent its own blockchain wallet: balances, USDC transfers and
+[x402](https://x402.org) payments, under a spending policy the agent cannot
+change.
+
+The `keyban` command serves the wallet's tools two ways: `keyban mcp` as an MCP
+server, and `keyban wallet <tool>` as one subcommand per tool, for scripts and
+humans.
+
+Registry name: `io.keyban.mcp/agent-wallet`.
+
+`keyban mcp` runs locally over stdio, next to your MCP client. It holds one share
+of a FROST threshold key in your OS keyring; Keyban holds the other. No single
+side can move funds alone, and the model never sees either share or your API
+key.
+
+## You need a Keyban wallet first
+
+**This server drives a wallet Keyban provisions. It does not create one, and it
+has nothing to drive without one** — installing the package on its own gets you
+a server offering only `setup_instructions` and the guide tool `get_instructions`,
+which point back here. The
+threshold key is the reason: one share lives here, the other lives with us, so
+there is a Keyban side to every wallet by construction and no configuration can
+replace it.
+
+So the order is:
+
+1. **Get a Keyban account** at <https://keyban.io>.
+2. **Create an agent wallet** in the admin app, or from your assistant with the
+   Keyban admin MCP (`https://mcp.keyban.io/mcp`). It provisions the wallet, its
+   API key, and a one-shot invite key that authorises this client as a signer.
+3. **Take the configuration the wallet's page in the admin app hands you** —
+   either the environment block for the table below, or a ready-to-install
+   `.mcpb` bundle with the values already in it.
+4. **Then** install, with those values in the environment.
+
+An [agent skill](https://docs.keyban.io/.well-known/agent-skills/keyban-agent-wallet/SKILL.md)
+walks an AI agent through the same steps, then through operating the wallet.
+
+## Install
+
+Once you have the credentials from step 3:
+
+```bash
+npx -y @keyban/cli@latest mcp
+```
+
+Keep the `@latest`: without a version, npx reuses the copy it cached on first
+run, and a restart never picks up a new release.
+
+Or install the command once and call the tools directly:
+
+```bash
+npm install -g @keyban/cli
+keyban wallet balance
+keyban wallet x402-pay --url https://example.com/paid --max-amount 0.01
+keyban wallet --help
+```
+
+With Claude Code:
+
+```bash
+claude mcp add agent-wallet \
+  -e KEYBAN_API_KEY=… \
+  -e KEYBAN_APP_ID=… \
+  -e KEYBAN_INVITE_KEY=0x… \
+  -e KEYBAN_WALLET_ADDRESS=0x… \
+  -e KEYBAN_NETWORK=… \
+  -- npx -y @keyban/cli@latest mcp
+```
+
+On first boot the server runs a key generation, keeps its share in your OS
+keyring, and registers itself on chain as a signer of that wallet using the
+invite key. That happens once per machine; the invite key is spent by it.
+
+## Configuration
+
+The five required values all come from step 2 — none of them is something you
+can pick yourself.
+
+| Variable | Required | What it is |
+|---|---|---|
+| `KEYBAN_API_KEY` | yes | API key of the application the wallet belongs to. Never exposed to the model. |
+| `KEYBAN_APP_ID` | yes | Identifier of the Keyban application. |
+| `KEYBAN_INVITE_KEY` | yes | One-shot ECDSA private key authorizing this client's first-boot registration as a signer. |
+| `KEYBAN_WALLET_ADDRESS` | yes | Address of the account this server drives. |
+| `KEYBAN_NETWORK` | yes | Network the wallet operates on: `BaseMainnet`, `BaseSepolia`, `XdcMainnet` or `XdcApothem`. |
+| `KEYBAN_BASE_URL` | no | Backend base URL, or one of `dev`, `testing`, `staging`, `prod`, `sandbox`. Defaults to `https://api.prod.keyban.io`. |
+| `KEYBAN_DKG_BLOB` | no | Pre-generated signer share, base64 JSON. For runtimes with no OS keyring; it does not replace the invite key. |
+| `MCP_LOG_FILE` | no | Path the server writes its log to. |
+| `MCP_LOG_LEVEL` | no | `debug`, `info`, `warn` or `error`. Defaults to `info` for `keyban mcp`, `warn` for `keyban wallet`. |
+
+`keyban mcp --http` serves stateless streamable-HTTP on `0.0.0.0:8000`,
+`POST /mcp`, for Amazon Bedrock AgentCore. It has no authentication of its own:
+AgentCore authenticates callers before they reach it. Anywhere else it is an
+open wallet endpoint, so use it on AgentCore only.
+
+## Tools
+
+Each tool is also a `keyban wallet` subcommand, its name in kebab-case
+(`x402_pay` → `keyban wallet x402-pay`) and its arguments as options.
+
+Read-only:
+
+| Tool | What it does |
+|---|---|
+| `get_instructions` | Read the agent wallet guide (the `keyban-agent-wallet` skill) |
+| `api_status` | Check Keyban API status |
+| `get_account_info` | Get wallet account info |
+| `balance` | Check wallet balance |
+| `list_expense_transactions` | List wallet transactions |
+| `expense_stats` | Get spending statistics |
+| `wait_for_intent` | Wait for approval decisions |
+| `x402_info` | Inspect the x402 price of a URL |
+| `discover_x402_services` | Search the x402 service directory |
+
+Writing:
+
+| Tool | What it does |
+|---|---|
+| `sign_message` | Sign a message |
+| `cancel_intent` | Cancel a pending payment intent |
+| `transfer_usdc` | Transfer USDC — moves funds |
+| `x402_pay` | Pay for an x402 resource — moves funds |
+
+Every tool carries a `title` and the applicable `readOnlyHint` or
+`destructiveHint`, so a client can tell the two groups apart before calling
+anything.
+
+## Spending policy
+
+Transfers and x402 payments are checked against the wallet's policy on the
+Keyban side. A call the policy will not clear on its own does not fail
+silently: it comes back naming a payment intent that needs a human decision.
+`wait_for_intent` blocks until the owner approves or declines, and the agent
+retries once it is approved. The policy lives with the wallet, not with this
+process, so editing this server's configuration cannot widen it.
+
+## Trust boundary
+
+The share and the API key are protected by your user account, nothing finer.
+On Linux (Secret Service) and Windows (Credential Manager) the OS keyring
+grants no per-program access: any program running as you can read them, and
+can run `keyban` too. What bounds such a program is the same thing that bounds
+the agent: Keyban co-signs every signature and applies the wallet's policy
+first. Treat the machine account that holds the share like one that holds an
+SSH key.
+
+If you suspect the share or the API key leaked, rotate them: add a new signer
+to the wallet, set it up, then delete the old signer. Deleting it removes its
+key from the wallet on chain and revokes its API key, so the leaked pair can
+no longer sign nor reach the API. The wallet address does not change.
+
+## Documentation
+
+<https://docs.keyban.io/>
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/SKILL.md

@@ -0,0 +1,147 @@
+---
+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