Rename wallet to agent allowance across all user-facing interfaces

Renames the user-facing concept from "wallet" to "agent allowance" across
MCP tools, CLI commands, OpenClaw scripts, and all documentation. Technical
wire-level terms (X-Run402-Wallet header, API parameter names) are preserved.
Includes auto-migration from wallet.json to allowance.json on first access.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MajorTal

CLAUDE.md

@@ -54,9 +54,9 @@ When adding a new tool/command, add it to the `SURFACE` array in `sync.test.ts`.
 
 The `core/` module contains shared logic imported by all three interfaces:
 
-- **`config.ts`** — Path resolution and env vars: `getApiBase()`, `getConfigDir()`, `getKeystorePath()`, `getWalletPath()`.
-- **`wallet.ts`** — `readWallet()`, `saveWallet()` with atomic writes (temp-file + rename, mode 0600).
-- **`wallet-auth.ts`** — EIP-191 signing with `@noble/curves`. `getWalletAuthHeaders()` returns headers or null.
+- **`config.ts`** — Path resolution and env vars: `getApiBase()`, `getConfigDir()`, `getKeystorePath()`, `getAllowancePath()`.
+- **`allowance.ts`** — `readAllowance()`, `saveAllowance()` with atomic writes (temp-file + rename, mode 0600).
+- **`allowance-auth.ts`** — EIP-191 signing with `@noble/curves`. `getAllowanceAuthHeaders()` returns headers or null.
 - **`keystore.ts`** — Unified project credential store. Object schema: `{projects: {id: {anon_key, service_key, tier, lease_expires_at}}}`. Auto-migrates legacy array format and `expires_at` → `lease_expires_at`. Functions: `loadKeyStore()`, `saveKeyStore()`, `getProject()`, `saveProject()`, `removeProject()`.
 - **`client.ts`** — `apiRequest()` fetch wrapper. Handles JSON/text responses, 402 payment detection.
 
@@ -66,15 +66,15 @@ Core functions return `null` or throw — they never call `process.exit()`. Each
 
 Thin re-export layer over `core/dist/` plus MCP-specific wrappers:
 
-- **`config.ts`**, **`client.ts`**, **`keystore.ts`**, **`wallet.ts`** — re-export from core
-- **`wallet-auth.ts`** — re-exports core's `getWalletAuthHeaders()` + adds `requireWalletAuth()` which returns MCP error shape
+- **`config.ts`**, **`client.ts`**, **`keystore.ts`**, **`allowance.ts`** — re-export from core
+- **`allowance-auth.ts`** — re-exports core's `getAllowanceAuthHeaders()` + adds `requireAllowanceAuth()` which returns MCP error shape
 - **`errors.ts`** — MCP-specific error formatting (`formatApiError`, `projectNotFound`)
 - **`index.ts`** — Entry point. Registers all tools via `McpServer`.
 - **`tools/*.ts`** — Each tool exports a Zod schema + async handler
 
 ### CLI (`cli/`)
 
-- **`cli/lib/config.mjs`** — Imports from `core/dist/`, adds CLI wrappers (`walletAuthHeaders()` with process.exit, `findProject()` with process.exit). Re-exports core keystore functions.
+- **`cli/lib/config.mjs`** — Imports from `core/dist/`, adds CLI wrappers (`allowanceAuthHeaders()` with process.exit, `findProject()` with process.exit). Re-exports core keystore functions.
 - **`cli/lib/paid-fetch.mjs`** — Shared `setupPaidFetch()` using viem + @x402/fetch for paid endpoints.
 - **`cli/lib/*.mjs`** — Each module exports `async run(sub, args)` with CLI output format.
 

README.md

@@ -10,7 +10,7 @@
 [![npm: run402](https://img.shields.io/npm/v/run402?label=run402)](https://www.npmjs.com/package/run402)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-Developer tools for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, serverless functions, generate images, and manage x402 wallets. Available as an MCP server, an OpenClaw skill, and a CLI.
+Developer tools for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, serverless functions, generate images, and manage agent allowances. Available as an MCP server, an OpenClaw skill, and a CLI.
 
 English | [简体中文](./README.zh-CN.md)
 
@@ -60,13 +60,13 @@ npx run402-mcp
 | `publish_app` | Publish a project as a forkable app. |
 | `list_versions` | List published versions of a project. |
 | `get_quote` | Get tier pricing. Free, no auth required. |
-| `set_tier` | Subscribe, renew, or upgrade wallet tier. Auto-detects action. Handles x402 payment. |
+| `set_tier` | Subscribe, renew, or upgrade tier. Auto-detects action. Handles x402 payment. |
 | `archive_project` | Archive a project and remove from local key store. |
-| `check_balance` | Check billing account balance for a wallet address. |
-| `list_projects` | List all active projects for a wallet address. |
-| `wallet_status` | Check local wallet status — address, network, funding. |
-| `wallet_create` | Create a new local wallet (Base Sepolia testnet). |
-| `wallet_export` | Export the local wallet address. |
+| `check_balance` | Check billing account balance for an agent allowance address. |
+| `list_projects` | List all active projects for an agent allowance address. |
+| `allowance_status` | Check local agent allowance status — address, network, funding. |
+| `allowance_create` | Create a new local agent allowance (Base Sepolia testnet). |
+| `allowance_export` | Export the local agent allowance address. |
 | `request_faucet` | Request free testnet USDC from the Run402 faucet. |
 | `generate_image` | Generate a PNG image from a text prompt. $0.03 via x402. |
 
@@ -79,8 +79,8 @@ A standalone CLI is available in the [`cli/`](./cli/) directory.
 ```bash
 npm install -g run402
 
-run402 wallet create
-run402 wallet fund
+run402 allowance create
+run402 allowance fund
 run402 deploy --tier prototype --manifest app.json
 ```
 

SECURITY.md

@@ -33,8 +33,8 @@ The Run402 API (`api.run402.com`) is operated by Kychee LLC. Report API-side vul
 
 ## Security Design
 
-- **Credential storage**: Project keys and wallet private keys are stored locally at `~/.config/run402/` with `0600` permissions (owner read/write only). Atomic writes via temp-file + rename prevent partial-write corruption.
+- **Credential storage**: Project keys and allowance private keys are stored locally at `~/.config/run402/` with `0600` permissions (owner read/write only). Atomic writes via temp-file + rename prevent partial-write corruption.
 - **No secrets in transit to MCP clients**: The MCP server never sends private keys or service keys in tool responses. Keys are stored locally and used internally for API authentication.
-- **Wallet isolation**: Wallet private keys never leave the local machine. They are used only for signing x402 payment transactions.
+- **Allowance isolation**: Allowance private keys never leave the local machine. They are used only for signing x402 payment transactions.
 - **SQL safety**: The API blocks dangerous SQL operations (CREATE EXTENSION, COPY PROGRAM, ALTER SYSTEM, GRANT/REVOKE, etc.) at the gateway level.
 - **Schema isolation**: Each project runs in its own Postgres schema with cross-schema access blocked.

SKILL.md

@@ -150,7 +150,7 @@ Deploy a static site (HTML/CSS/JS/images). Files are uploaded to S3 and served v
 }
 ```
 
-Free with active tier. Requires wallet auth.
+Free with active tier. Requires allowance auth.
 
 **Examples:**
 ```
@@ -316,8 +316,8 @@ Run402 uses the x402 HTTP payment protocol. Here's what you need to know:
 
 **How to handle it:**
 1. Explain to the user what the cost is (e.g., "$0.10 for a 7-day prototype database")
-2. If the user has a wallet set up, help them complete the payment
-3. If not, guide them through wallet setup (see Wallet Setup below)
+2. If the user has an allowance set up, help them complete the payment
+3. If not, guide them through allowance setup (see Agent Allowance Setup below)
 4. Once payment is complete, retry the same tool call
 
 **Pricing tiers:**
@@ -358,21 +358,21 @@ Run402 uses the x402 HTTP payment protocol. Here's what you need to know:
 
 **Idempotency:** When provisioning or renewing, include an `Idempotency-Key` header to prevent double-charging on retries. The MCP tools handle this automatically when possible.
 
-## Wallet Setup
+## Agent Allowance Setup
 
-To pay Run402, the user needs a crypto wallet with USDC on Base. If they don't have one yet, here are the options:
+To pay Run402, the user needs an agent allowance with USDC on Base. If they don't have one yet, here are the options:
 
-**Option A: Coinbase AgentKit (recommended)** — Gives you a wallet on Base with built-in x402 support. No KYC, no manual key management.
+**Option A: Coinbase AgentKit (recommended)** — Gives you an allowance on Base with built-in x402 support. No KYC, no manual key management.
 
 **Option B: AgentPayy** — Auto-bootstraps an MPC wallet on Base using Coinbase CDP. Purpose-built for x402.
 
 **Option C: x402 OpenClaw Skill** — Install the x402 skill from ClawHub for x402 payment capabilities.
 
-**Funding the wallet:** Once the user has a wallet address, they need USDC on Base. The simplest path: download Coinbase Wallet, buy USDC, send to the wallet address. Base transactions cost under $0.01.
+**Funding the allowance:** Once the user has an allowance address, they need USDC on Base. The simplest path: download Coinbase Wallet, buy USDC, send to the allowance address. Base transactions cost under $0.01.
 
 **Testnet:** For testing without real money, use Base Sepolia testnet. Get test USDC from Circle's faucet. The Run402 API supports testnet at the same endpoints.
 
-**Asking for an allowance:** If the user's human controls the wallet funding, suggest:
+**Requesting an allowance:** If the user's human controls the allowance funding, suggest:
 - Trial: $1 in USDC covers 10 prototype databases
 - Monthly: $10/month covers two Hobby projects or 100 prototypes
 - One-off: $10 for a project plus buffer for renewals

SKILL.test.ts

@@ -99,7 +99,7 @@ const REQUIRED_SECTIONS = [
   "Payment Handling",
   "Tips & Guardrails",
   "Tools Reference",
-  "Wallet Setup",
+  "Agent Allowance Setup",
 ];
 
 describe("body required sections", () => {

cli-e2e.test.mjs

@@ -353,60 +353,60 @@ beforeEach(() => {
 
 describe("CLI e2e happy path", () => {
 
-  // ── Wallet ──────────────────────────────────────────────────────────────
+  // ── Allowance ───────────────────────────────────────────────────────────
 
-  it("wallet create", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance create", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("create", []);
     captureStop();
     assert.ok(captured().includes("ok"), "should output ok status");
-    assert.ok(existsSync(join(tempDir, "wallet.json")), "wallet.json should exist");
+    assert.ok(existsSync(join(tempDir, "allowance.json")), "allowance.json should exist");
   });
 
-  it("wallet status", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance status", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("status", []);
     captureStop();
     assert.ok(captured().includes("ok"), "should show ok status");
   });
 
-  it("wallet fund", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance fund", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("fund", []);
     captureStop();
     // Fund polls for balance — mock returns positive immediately
     assert.ok(captured().includes("base-sepolia"), "should show balance or faucet result");
   });
 
-  it("wallet export", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance export", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("export", []);
     captureStop();
-    assert.ok(captured().includes("0x"), "should print wallet address");
+    assert.ok(captured().includes("0x"), "should print allowance address");
   });
 
-  it("wallet balance", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance balance", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("balance", []);
     captureStop();
     assert.ok(captured().includes("base-sepolia_usd_micros"), "should show balance");
   });
 
-  it("wallet checkout", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance checkout", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("checkout", ["--amount", "5000000"]);
     captureStop();
     assert.ok(captured().includes("checkout_url"), "should return checkout URL");
   });
 
-  it("wallet history", async () => {
-    const { run } = await import("./cli/lib/wallet.mjs");
+  it("allowance history", async () => {
+    const { run } = await import("./cli/lib/allowance.mjs");
     captureStart();
     await run("history", ["--limit", "5"]);
     captureStop();
@@ -774,16 +774,16 @@ describe("CLI e2e happy path", () => {
     assert.ok(captured().includes("deleted") || captured().includes("ok"), "should delete project");
   });
 
-  // ── Init (runs after wallet exists) ─────────────────────────────────────
+  // ── Init (runs after allowance exists) ──────────────────────────────────
 
-  it("init (wallet already exists)", async () => {
+  it("init (allowance already exists)", async () => {
     const { run } = await import("./cli/lib/init.mjs");
     captureStart();
     await run();
     captureStop();
     const out = captured();
     assert.ok(out.includes("Config"), "should show config dir");
-    assert.ok(out.includes("Wallet"), "should show wallet");
+    assert.ok(out.includes("Allowance"), "should show allowance");
     assert.ok(out.includes("Balance") || out.includes("USDC"), "should show balance");
     assert.ok(out.includes("Tier") || out.includes("prototype"), "should show tier");
   });

cli/README.md

@@ -1,6 +1,6 @@
 # run402 CLI
 
-Command-line interface for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 micropayments.
+Command-line interface for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, generate images, and manage agent allowances via x402 micropayments.
 
 ## Installation
 
@@ -17,27 +17,27 @@ npx run402 <command>
 ## Getting Started
 
 ```bash
-# 1. Create a local wallet
-run402 wallet create
+# 1. Create a local agent allowance
+run402 allowance create
 
 # 2. Fund it with test USDC (Base Sepolia faucet)
-run402 wallet fund
+run402 allowance fund
 
 # 3. Deploy your app
 run402 deploy --tier prototype --manifest app.json
 ```
 
 ## Commands
 
-### `run402 wallet`
+### `run402 allowance`
 
-Manage your local x402 wallet.
+Manage your local agent allowance.
 
 ```bash
-run402 wallet create    # Generate a new wallet
-run402 wallet status    # Show address, network, funding status
-run402 wallet fund      # Request test USDC from the faucet
-run402 wallet export    # Print wallet address (for scripting)
+run402 allowance create    # Generate a new allowance
+run402 allowance status    # Show address, network, funding status
+run402 allowance fund      # Request test USDC from the faucet
+run402 allowance export    # Print allowance address (for scripting)
 ```
 
 ### `run402 deploy`
@@ -98,15 +98,15 @@ Every command supports `--help` / `-h`:
 
 ```bash
 run402 --help
-run402 wallet --help
+run402 allowance --help
 run402 deploy --help
 run402 projects --help
 run402 image --help
 ```
 
 ## Notes
 
-- Wallet stored at `~/.run402/wallet.json`
+- Agent allowance stored at `~/.run402/allowance.json`
 - Project credentials stored at `~/.run402/projects.json`
 - Network: Base Sepolia (testnet) — USDC for x402 payments
 - Payments are handled automatically — no manual signing required

cli/cli.mjs

@@ -13,8 +13,8 @@ Usage:
   run402 <command> [subcommand] [options]
 
 Commands:
-  init        Set up wallet, funding, and check tier status
-  wallet      Manage your x402 wallet (create, fund, balance, status)
+  init        Set up allowance, funding, and check tier status
+  allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
   deploy      Deploy a full-stack app or static site (requires active tier)
@@ -31,8 +31,8 @@ Commands:
 Run 'run402 <command> --help' for detailed usage of each command.
 
 Examples:
-  run402 wallet create
-  run402 wallet fund
+  run402 allowance create
+  run402 allowance fund
   run402 deploy --manifest app.json
   run402 projects list
   run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
@@ -57,8 +57,8 @@ switch (cmd) {
     await run();
     break;
   }
-  case "wallet": {
-    const { run } = await import("./lib/wallet.mjs");
+  case "allowance": {
+    const { run } = await import("./lib/allowance.mjs");
     await run(sub, rest);
     break;
   }

cli/lib/agent.mjs

@@ -1,12 +1,12 @@
-import { API, walletAuthHeaders } from "./config.mjs";
+import { API, allowanceAuthHeaders } from "./config.mjs";
 
 const HELP = `run402 agent — Manage agent identity
 
 Usage:
   run402 agent contact --name <name> [--email <email>] [--webhook <url>]
 
 Notes:
-  - Free with wallet auth
+  - Free with allowance auth
   - Registers contact info so Run402 can reach your agent
   - Only name is required; email and webhook are optional
 
@@ -23,7 +23,7 @@ async function contact(args) {
     if (args[i] === "--webhook" && args[i + 1]) webhook = args[++i];
   }
   if (!name) { console.error(JSON.stringify({ status: "error", message: "Missing --name <name>" })); process.exit(1); }
-  const authHeaders = await walletAuthHeaders();
+  const authHeaders = await allowanceAuthHeaders();
 
   const body = { name };
   if (email) body.email = email;