agent402-openclaw 0.2.1 → 0.3.1

package/README.md

@@ -42,6 +42,18 @@ export AGENT402_WALLET_KEY=0x...     # an EVM key holding USDC on Base
 With no credits key present the proxy signs an x402 payment per call from that
 wallet. The key never leaves the machine.
 
+Two ways the wallet can pay a metered call:
+
+- **exact** (default): the 402 quotes the call from its body (input + your
+  `max_tokens` at the model's list price, x1.15) and the wallet pays that quote.
+- **upto, actual usage**: run `agent402-openclaw permit2-approve` once (one USDC
+  approval transaction on Base; the wallet needs a little ETH for gas). From
+  then on the proxy authorizes the quote as a CEILING and the gateway settles
+  what the call actually cost x1.15, so a short answer costs a fraction of the
+  quote. `agent402-openclaw doctor` says which mode the wallet is in.
+
+Card / credits buyers already pay actual usage on metered calls.
+
 ## Models and pricing
 
 `auto` (routed per prompt, flat $0.01/call) plus every id from
@@ -65,5 +77,21 @@ 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 permit2-approve [--rpc URL]` (one-time USDC approval so the wallet pays actual usage over upto)
+
+## What else the same key buys
+
+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
+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.
+
+Why pay here, with every claim linked to its proof: https://agent402.tools/why.
+Usage is priced under a ceiling quoted before you pay, a failed call is not
+charged and the receipt proves it, a keyed retry never pays twice, and uptime and transactions are
+published from outside production.
 
 Zero dependencies. MIT. Maintained by Havok Holdings LLC.

package/cli.js

@@ -7,7 +7,7 @@ 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 } from "./index.js";
+import { STATE_DIR, CREDITS_KEY_FILE, resolveCreditsKey, 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";
@@ -45,7 +45,7 @@ function mergeInto(target, block, { port = DEFAULT_PORT } = {}) {
 
 async function main() {
   if (cmd === "help" || has("--help")) {
-    out("agent402-openclaw setup [--credits-key a402_...|-] [--write] [--flat] | proxy [--port N] [--upstream URL] [--flat] | doctor");
+    out("agent402-openclaw setup [--credits-key a402_...|-] [--write] [--flat] | proxy [--port N] [--upstream URL] [--flat] | doctor | permit2-approve [--rpc URL]");
     return 0;
   }
   const upstream = stripTrailingSlashes(opt("--upstream") || process.env.AGENT402_UPSTREAM || DEFAULT_UPSTREAM);
@@ -108,11 +108,42 @@ async function main() {
     await new Promise(() => {}); // run until killed
   }
 
+  // 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; }
+    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);
+      const rpc = (opt("--rpc") || process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim();
+      const pub = createPublicClient({ chain: base, transport: http(rpc) });
+      const read = () => pub.readContract(getPermit2AllowanceReadParams({ tokenAddress: USDC_BASE, ownerAddress: account.address }));
+      if (uptoReady(await read())) { out(`already approved: ${account.address} has a Permit2 allowance on USDC (Base); the proxy pays actual usage (upto)`); return 0; }
+      const tx = createPermit2ApprovalTx(USDC_BASE);
+      const wallet = createWalletClient({ account, chain: base, transport: http(rpc) });
+      const hash = await wallet.sendTransaction({ to: tx.to, data: tx.data });
+      out(`approval sent: ${hash} (waiting for confirmation)`);
+      await pub.waitForTransactionReceipt({ hash, timeout: 120_000 });
+      out(uptoReady(await read()) ? `approved: ${account.address} can now pay actual usage over upto. Restart the gateway.` : "transaction confirmed but the allowance still reads low - check the wallet on basescan");
+      return 0;
+    } catch (e) { console.error(`permit2-approve failed: ${String(e?.message || e).slice(0, 300)}`); return 1; }
+  }
+
   if (cmd === "doctor") {
     const key = resolveCreditsKey();
     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 || "")) {
+      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 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"}`);
+      } catch (e) { out(`wallet: allowance unreadable (${String(e?.message || e).slice(0, 80)})`); }
+    }
     try { const r = await loadRoutes(upstream, fetch, { pricing }); out(`gateway: ok, ${r.size} models (${pricing} pricing: ${[...r.values()].filter((x) => x.metered).length} metered)`); } catch (e) { out(`gateway: unreachable (${e?.message || e})`); return 1; }
     if (key) {
       try {

package/index.js

@@ -22,18 +22,55 @@ export function resolveCreditsKey(pluginConfig = {}) {
   return null;
 }
 
-/** Optional x402 wallet payment: only when the peer deps are installed and a key is present. */
+// x402 wallet payment - optional (peer deps) and, when the wallet has a
+// Permit2 allowance, METERED: the `upto` scheme authorizes a CEILING (the
+// per-request quote) and the gateway settles actual usage x 1.15, the way a
+// per-token router bills. Without the allowance it pays `exact` (the quote).
+export const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const BASE_CAIP2 = "eip155:8453";
+export const DEFAULT_BASE_RPC = "https://mainnet.base.org";
+// Permit2 approvals are max-uint by convention; anything this large is "approved".
+export const PERMIT2_READY_MIN = 10n ** 12n; // 1,000,000 USDC (6 decimals): a real approval, not dust
+
+/** Which 402 accept to pay: upto on Base when the client can (settle-actual),
+ *  else exact on Base, else the first the client supports. Pure. */
+export function selectAccept(accepts, { preferUpto = true } = {}) {
+  const list = Array.isArray(accepts) ? accepts : [];
+  if (preferUpto) { const u = list.find((a) => a?.scheme === "upto" && a?.network === BASE_CAIP2); if (u) return u; }
+  return list.find((a) => a?.scheme === "exact" && a?.network === BASE_CAIP2) || list[0];
+}
+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;
   try {
-    const [{ wrapFetchWithPayment }, { privateKeyToAccount }] = await Promise.all([import("@x402/fetch"), import("viem/accounts")]);
-    const { toClientEvmSigner } = await import("@x402/evm");
-    const { registerExactEvmScheme } = await import("@x402/evm/exact/client");
-    const { x402Client } = await import("@x402/fetch");
-    const client = new x402Client();
-    registerExactEvmScheme(client, { signer: toClientEvmSigner(privateKeyToAccount(pk)) });
-    return wrapFetchWithPayment(fetch, client);
+    const [{ wrapFetchWithPayment, x402Client }, { privateKeyToAccount }, { toClientEvmSigner }, { registerExactEvmScheme }] = await Promise.all([
+      import("@x402/fetch"), import("viem/accounts"), import("@x402/evm"), import("@x402/evm/exact/client"),
+    ]);
+    const account = privateKeyToAccount(pk);
+    const signer = toClientEvmSigner(account);
+    // Upto needs a Permit2 allowance on USDC (one approval transaction, ever).
+    let upto = false;
+    try {
+      const [{ UptoEvmScheme, getPermit2AllowanceReadParams }, { createPublicClient, http }, { base }] = await Promise.all([import("@x402/evm/upto/client"), import("viem"), import("viem/chains")]);
+      const pub = createPublicClient({ chain: base, transport: http((pluginConfig.baseRpc || process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim()) });
+      const allowance = await pub.readContract(getPermit2AllowanceReadParams({ tokenAddress: USDC_BASE, ownerAddress: account.address }));
+      upto = uptoReady(allowance);
+      const client = new x402Client((v, accepts) => selectAccept(accepts, { preferUpto: upto }));
+      registerExactEvmScheme(client, { signer });
+      if (upto) client.register(BASE_CAIP2, new UptoEvmScheme(signer));
+      log(upto
+        ? `[agent402-openclaw] x402 wallet ${account.address}: paying actual usage (upto, Permit2 allowance present) on Base; exact elsewhere`
+        : `[agent402-openclaw] x402 wallet ${account.address}: paying the per-request quote (exact). To pay actual usage instead, run \`agent402-openclaw permit2-approve\` once (one USDC approval transaction on Base; needs a little ETH for gas)`);
+      return wrapFetchWithPayment(fetch, client);
+    } catch (e) {
+      // The allowance read or the upto scheme failed: exact still works.
+      log(`[agent402-openclaw] upto unavailable (${String(e?.message || e).slice(0, 120)}) - paying exact`);
+      const client = new x402Client((v, accepts) => selectAccept(accepts, { preferUpto: false }));
+      registerExactEvmScheme(client, { signer });
+      return wrapFetchWithPayment(fetch, client);
+    }
   } catch (e) {
     log(`[agent402-openclaw] x402 wallet payment unavailable (${e?.message || e}); install @x402/fetch @x402/evm viem, or use a credits key`);
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-openclaw",
-  "version": "0.2.1",
+  "version": "0.3.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",