agent402-openclaw 0.3.1 → 0.4.1

package/README.md

@@ -11,12 +11,21 @@ Guide: https://agent402.tools/guides/openclaw-model-provider
 
 ```bash
 openclaw plugins install agent402-openclaw
-AGENT402_CREDITS_KEY=a402_... npx agent402-openclaw setup --write   # key by env (or `--credits-key -` on stdin); buy one by card at https://agent402.tools/credits
+npx agent402-openclaw setup --write        # no key? it mints a wallet and prints the address to fund
 openclaw gateway restart
 ```
 
+With no credits key and no `AGENT402_WALLET_KEY`, `setup` generates an EVM
+wallet into `~/.openclaw/agent402/wallet.key` (0600, the only copy, never
+printed) and prints its address: send it USDC on Base and every call is paid
+from it over x402. `agent402-openclaw wallet` shows the address and balance;
+`--no-wallet` skips the generation. Prefer a card? Buy a pack at
+https://agent402.tools/credits and run
+`AGENT402_CREDITS_KEY=a402_... npx agent402-openclaw setup --write` (key by env,
+or `--credits-key -` on stdin).
+
 (`openclaw plugins install` copies the plugin into `~/.openclaw/extensions` and
-does not link its CLI, hence `npx`.) `setup` stores the key under
+does not link its CLI, hence `npx`.) `setup` stores a credits key under
 `~/.openclaw/agent402/credits.key` (0600) and prints the `openclaw.json` block;
 add `--write` to merge it in. The primary model it writes is the cheapest
 metered model that can hold OpenClaw's own prompt: OpenClaw sends roughly 70k
@@ -77,6 +86,7 @@ the key.
 - `agent402-openclaw setup [--credits-key K | --credits-key - (stdin) | AGENT402_CREDITS_KEY env] [--write] [--port N] [--flat]`
 - `agent402-openclaw proxy [--port N] [--upstream URL]`
 - `agent402-openclaw doctor`
+- `agent402-openclaw wallet [--rpc URL]` (address + USDC balance of the wallet the proxy pays from)
 - `agent402-openclaw permit2-approve [--rpc URL]` (one-time USDC approval so the wallet pays actual usage over upto)
 
 ## What else the same key buys
@@ -84,7 +94,7 @@ the key.
 The key or wallet that pays for chat also pays for the rest of the gateway and
 the catalog, with one 402 shape and one receipt shape: OpenAI Responses and
 Anthropic Messages wires, embeddings, rerank, images, video, speech,
-transcription, grounded answers with citations, 500+ deterministic tools over
+transcription, grounded answers with citations, 500+ tools over
 MCP or HTTP, wallet-keyed memory, finished reports (dossiers, insider flow, 13F,
 domain audits, token risk, deep research) and monitors, plus routing that buys
 from proven external sellers on the agent's behalf.

package/cli.js

@@ -7,10 +7,10 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, statSync
 import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { STATE_DIR, CREDITS_KEY_FILE, resolveCreditsKey, resolvePayFetch, USDC_BASE, DEFAULT_BASE_RPC, uptoReady } from "./index.js";
+import { STATE_DIR, CREDITS_KEY_FILE, WALLET_KEY_FILE, resolveCreditsKey, resolveWalletKey, resolvePayFetch, USDC_BASE, DEFAULT_BASE_RPC, uptoReady } from "./index.js";
 import { startProxy, loadRoutes, DEFAULT_UPSTREAM } from "./proxy.js";
 import { providerModelsConfig, stripTrailingSlashes, defaultPrimary, AUTO_ID, OPENCLAW_MIN_INPUT_CHARS } from "./models.js";
-import { DEFAULT_PORT, PROVIDER_ID } from "./provider.js";
+import { DEFAULT_PORT, PLUGIN_ID, PROVIDER_ID } from "./provider.js";
 
 const args = process.argv.slice(2);
 const cmd = args[0] || "help";
@@ -38,14 +38,32 @@ function mergeInto(target, block, { port = DEFAULT_PORT } = {}) {
   // on 8412 and OpenClaw dialing a port nobody listened on (real-install test).
   if (port !== DEFAULT_PORT) {
     t.plugins = t.plugins || {}; t.plugins.entries = t.plugins.entries || {};
-    t.plugins.entries[PROVIDER_ID] = { ...(t.plugins.entries[PROVIDER_ID] || {}), config: { ...(t.plugins.entries[PROVIDER_ID]?.config || {}), port } };
+    t.plugins.entries[PLUGIN_ID] = { ...(t.plugins.entries[PLUGIN_ID] || {}), config: { ...(t.plugins.entries[PLUGIN_ID]?.config || {}), port } };
   }
   return t;
 }
 
+// Mint a fresh EVM wallet into WALLET_KEY_FILE (0600). Needs viem (an optional
+// peer, same as x402 payment itself); returns null when it is not installed so
+// setup can fall back to the card path instead of failing.
+async function generateWallet() {
+  try {
+    const [{ generatePrivateKey, privateKeyToAccount }] = await Promise.all([import("viem/accounts")]);
+    const pk = generatePrivateKey();
+    const account = privateKeyToAccount(pk);
+    mkdirSync(STATE_DIR(), { recursive: true });
+    writeFileSync(WALLET_KEY_FILE(), pk + "\n", { mode: 0o600, flag: "wx" }); // never overwrite an existing key
+    try { chmodSync(WALLET_KEY_FILE(), 0o600); } catch { /* best effort */ }
+    return { address: account.address };
+  } catch (e) {
+    if (e?.code === "EEXIST") { try { return { address: (await import("viem/accounts")).privateKeyToAccount(readFileSync(WALLET_KEY_FILE(), "utf8").trim()).address }; } catch { return null; } }
+    return null;
+  }
+}
+
 async function main() {
   if (cmd === "help" || has("--help")) {
-    out("agent402-openclaw setup [--credits-key a402_...|-] [--write] [--flat] | proxy [--port N] [--upstream URL] [--flat] | doctor | permit2-approve [--rpc URL]");
+    out("agent402-openclaw setup [--credits-key a402_...|-] [--no-wallet] [--write] [--flat] | proxy [--port N] [--upstream URL] [--flat] | wallet [--rpc URL] | doctor | permit2-approve [--rpc URL]");
     return 0;
   }
   const upstream = stripTrailingSlashes(opt("--upstream") || process.env.AGENT402_UPSTREAM || DEFAULT_UPSTREAM);
@@ -66,8 +84,26 @@ async function main() {
       writeFileSync(CREDITS_KEY_FILE(), key + "\n", { mode: 0o600 });
       try { chmodSync(CREDITS_KEY_FILE(), 0o600); } catch { /* best effort */ }
       out(`stored credits key at ${CREDITS_KEY_FILE()} (0600)`);
-    } else if (!resolveCreditsKey()) {
-      out(`no credits key yet: buy a pack by card at ${upstream}/credits, then rerun with --credits-key a402_...`);
+    } else if (!resolveCreditsKey() && !resolveWalletKey()) {
+      // No payment method at all: mint a wallet right here, print the address,
+      // and the user funds it with USDC on Base. Same first-run shape as a
+      // per-token router that prints a wallet at install; the card path
+      // (credits key) stays available. --no-wallet keeps the old behaviour.
+      if (has("--no-wallet")) {
+        out(`no payment method yet: buy a pack by card at ${upstream}/credits and rerun with --credits-key a402_..., or set AGENT402_WALLET_KEY`);
+      } else {
+        const w = await generateWallet();
+        if (w) {
+          out(`no credits key found, so a wallet was generated for you:`);
+          out(`  address: ${w.address}`);
+          out(`  key:     ${WALLET_KEY_FILE()} (0600; back it up, it is the only copy)`);
+          out(`fund it with USDC on Base (any amount; a call costs from $0.001), then every call is paid from it over x402.`);
+          out(`optional: \`agent402-openclaw permit2-approve\` once (needs a little ETH on Base for gas) to pay actual usage instead of the per-request quote.`);
+          out(`prefer a card? buy a pack at ${upstream}/credits and rerun with --credits-key a402_...`);
+        } else {
+          out(`no payment method yet: buy a pack by card at ${upstream}/credits and rerun with --credits-key a402_..., or install viem + @x402/fetch + @x402/evm and rerun to generate a wallet`);
+        }
+      }
     }
     let routes;
     try { routes = await loadRoutes(upstream, fetch, { pricing }); } catch (e) { console.error(`could not read ${upstream}/v1/models: ${e?.message || e}`); return 2; }
@@ -111,8 +147,8 @@ async function main() {
   // One-time USDC -> Permit2 approval on Base so the wallet can pay ACTUAL
   // usage over `upto` instead of the per-request quote over `exact`.
   if (cmd === "permit2-approve") {
-    const pk = (process.env.AGENT402_WALLET_KEY || "").trim();
-    if (!/^0x[0-9a-fA-F]{64}$/.test(pk)) { console.error("AGENT402_WALLET_KEY (0x + 64 hex) is required"); return 2; }
+    const pk = resolveWalletKey();
+    if (!pk) { console.error("no wallet: set AGENT402_WALLET_KEY (0x + 64 hex) or run `agent402-openclaw setup` to generate one"); return 2; }
     try {
       const [{ createPermit2ApprovalTx, getPermit2AllowanceReadParams }, { createWalletClient, createPublicClient, http }, { privateKeyToAccount }, { base }] = await Promise.all([import("@x402/evm/upto/client"), import("viem"), import("viem/accounts"), import("viem/chains")]);
       const account = privateKeyToAccount(pk);
@@ -130,15 +166,32 @@ async function main() {
     } catch (e) { console.error(`permit2-approve failed: ${String(e?.message || e).slice(0, 300)}`); return 1; }
   }
 
+  // Address + USDC balance of the wallet the proxy pays from. Read-only.
+  if (cmd === "wallet") {
+    const pk = resolveWalletKey();
+    if (!pk) { console.error("no wallet: run `agent402-openclaw setup` to generate one, or set AGENT402_WALLET_KEY"); return 2; }
+    try {
+      const [{ createPublicClient, http, erc20Abi, formatUnits }, { privateKeyToAccount }, { base }] = await Promise.all([import("viem"), import("viem/accounts"), import("viem/chains")]);
+      const account = privateKeyToAccount(pk);
+      const pub = createPublicClient({ chain: base, transport: http((opt("--rpc") || process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim()) });
+      const bal = await pub.readContract({ address: USDC_BASE, abi: erc20Abi, functionName: "balanceOf", args: [account.address] });
+      out(`address: ${account.address}`);
+      out(`USDC on Base: $${formatUnits(bal, 6)}`);
+      if (bal === 0n) out(`fund it: send USDC on Base (eip155:8453) to ${account.address}`);
+      return 0;
+    } catch (e) { console.error(`wallet: ${String(e?.message || e).slice(0, 200)}`); return 1; }
+  }
+
   if (cmd === "doctor") {
     const key = resolveCreditsKey();
+    const walletPk = resolveWalletKey();
     out(`upstream: ${upstream}`);
     out(`credits key: ${key ? `present (${key.slice(0, 8)}…)` : "none"}`);
-    out(`wallet key: ${/^0x[0-9a-fA-F]{64}$/.test(process.env.AGENT402_WALLET_KEY || "") ? "present" : "none"}`);
-    if (/^0x[0-9a-fA-F]{64}$/.test(process.env.AGENT402_WALLET_KEY || "")) {
+    out(`wallet key: ${walletPk ? "present" : "none"}`);
+    if (walletPk) {
       try {
         const [{ getPermit2AllowanceReadParams }, { createPublicClient, http }, { privateKeyToAccount }, { base }] = await Promise.all([import("@x402/evm/upto/client"), import("viem"), import("viem/accounts"), import("viem/chains")]);
-        const account = privateKeyToAccount(process.env.AGENT402_WALLET_KEY.trim());
+        const account = privateKeyToAccount(walletPk);
         const pub = createPublicClient({ chain: base, transport: http((process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim()) });
         const allowance = await pub.readContract(getPermit2AllowanceReadParams({ tokenAddress: USDC_BASE, ownerAddress: account.address }));
         out(`wallet ${account.address}: ${uptoReady(allowance) ? "pays actual usage (upto; Permit2 approved)" : "pays the per-request quote (exact) - run permit2-approve once to pay actual usage"}`);

package/index.js

@@ -5,12 +5,25 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { buildProvider, setActiveProxy, setCachedRoutes, DEFAULT_PORT, PROVIDER_ID } from "./provider.js";
+import { buildProvider, setActiveProxy, setCachedRoutes, DEFAULT_PORT, PLUGIN_ID } from "./provider.js";
 import { startProxy, loadRoutes, DEFAULT_UPSTREAM } from "./proxy.js";
 import { stripTrailingSlashes } from "./models.js";
 
 export const STATE_DIR = () => join(process.env.AGENT402_OPENCLAW_HOME || join(homedir(), ".openclaw"), "agent402");
 export const CREDITS_KEY_FILE = () => join(STATE_DIR(), "credits.key");
+export const WALLET_KEY_FILE = () => join(STATE_DIR(), "wallet.key");
+
+/** Wallet key precedence: plugin config > env > ~/.openclaw/agent402/wallet.key
+ *  (the wallet `setup` generates when no payment method exists yet). Only a
+ *  well-formed 0x + 64 hex key counts; anything else is "no wallet". */
+export function resolveWalletKey(pluginConfig = {}) {
+  const cands = [
+    typeof pluginConfig.walletKey === "string" ? pluginConfig.walletKey.trim() : "",
+    (process.env.AGENT402_WALLET_KEY || "").trim(),
+  ];
+  try { if (existsSync(WALLET_KEY_FILE())) cands.push(readFileSync(WALLET_KEY_FILE(), "utf8").trim()); } catch { /* unreadable */ }
+  return cands.find((k) => /^0x[0-9a-fA-F]{64}$/.test(k)) || null;
+}
 
 /** Credits key precedence: plugin config > env > ~/.openclaw/agent402/credits.key. */
 export function resolveCreditsKey(pluginConfig = {}) {
@@ -42,8 +55,8 @@ export function selectAccept(accepts, { preferUpto = true } = {}) {
 export const uptoReady = (allowance) => { try { return BigInt(allowance ?? 0) >= PERMIT2_READY_MIN; } catch { return false; } };
 
 export async function resolvePayFetch(pluginConfig = {}, log = () => {}) {
-  const pk = (pluginConfig.walletKey || process.env.AGENT402_WALLET_KEY || "").trim();
-  if (!/^0x[0-9a-fA-F]{64}$/.test(pk)) return null;
+  const pk = resolveWalletKey(pluginConfig);
+  if (!pk) return null;
   try {
     const [{ wrapFetchWithPayment, x402Client }, { privateKeyToAccount }, { toClientEvmSigner }, { registerExactEvmScheme }] = await Promise.all([
       import("@x402/fetch"), import("viem/accounts"), import("@x402/evm"), import("@x402/evm/exact/client"),
@@ -81,7 +94,7 @@ let started = null;
 let registeredOnce = false;
 
 const plugin = {
-  id: PROVIDER_ID,
+  id: PLUGIN_ID,
   name: "Agent402",
   description: "Agent402 model provider: routed + explicit models at a flat per-call price, paid by card or USDC.",
   register(api) {

package/openclaw.plugin.json

@@ -1,5 +1,5 @@
 {
-  "id": "agent402",
+  "id": "agent402-openclaw",
   "name": "Agent402",
   "description": "Agent402 model provider: auto-routed and explicit frontier models at a flat per-call price, paid by card (prepaid credits key) or in USDC over x402. Same key reaches 500+ pay-per-call tools.",
   "activation": {
@@ -19,7 +19,7 @@
       },
       "walletKey": {
         "type": "string",
-        "description": "Optional EVM private key for x402 USDC payment (needs @x402/fetch + @x402/evm + viem installed)."
+        "description": "Optional EVM private key for x402 USDC payment (needs @x402/fetch + @x402/evm + viem installed). Precedence: this, then AGENT402_WALLET_KEY, then the wallet `setup` generates at ~/.openclaw/agent402/wallet.key."
       },
       "port": {
         "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-openclaw",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "OpenClaw model provider for Agent402: auto-routed and explicit LLM models at a flat per-call price, paid by card (prepaid credits key) or in USDC over x402 through a local proxy. Zero dependencies; x402 wallet payment is an optional peer.",
   "type": "module",
   "main": "index.js",
@@ -24,7 +24,17 @@
   "openclaw": {
     "extensions": [
       "./index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.8.1"
+    },
+    "build": {
+      "openclawVersion": "2026.8.1"
+    },
+    "install": {
+      "minHostVersion": ">=2026.8.1",
+      "npmSpec": "agent402-openclaw"
+    }
   },
   "engines": {
     "node": ">=18"

package/provider.js

@@ -4,7 +4,17 @@
 // would 402 without the proxy's payment step in between).
 import { providerModelsConfig, routesFromCatalog } from "./models.js";
 
+// The MODEL PROVIDER id: what a user writes in openclaw.json ("agent402/auto").
+// User-facing and stable - renaming it would break every existing config.
 export const PROVIDER_ID = "agent402";
+// The PLUGIN id, which is a different thing: OpenClaw keys plugins.entries by
+// the MANIFEST id, and since 2026.8.1 it requires that id to equal the npm
+// package name ("Plugin manifest id ... differs from npm package name ...").
+// They were both "agent402", so nothing distinguished them until the host
+// started checking. Writing config under the provider id while the host reads
+// it under the manifest id is the same defect as the 2026-08-26 --port bug,
+// where setup moved the baseUrl and the service kept reading the old key.
+export const PLUGIN_ID = "agent402-openclaw";
 export const DEFAULT_PORT = 8412;
 
 let activeProxy = null;