agent402-openclaw 0.4.3 → 0.4.5

package/README.md

@@ -2,10 +2,11 @@
 
 Part of [Agent402](https://agent402.tools), the open-source paid door for AI agents.
 
-Agent402 as an [OpenClaw](https://openclaw.ai) model provider: auto-routed and
-explicit frontier models at a **flat per-call price**, paid **by card** (a prepaid
-credits key, no wallet) or in **USDC over x402** from a wallet. The same key and
-gateway reach Agent402's 500+ pay-per-call tools.
+Agent402 as an [OpenClaw](https://openclaw.ai) model provider: the auto-routed
+tier at a **flat per-call price** and explicit frontier models **priced per
+request** from the body, paid in **USDC over x402** from a wallet or with a
+prepaid credits key already issued (new credits are not on sale). The same key
+and gateway reach Agent402's 500+ pay-per-call tools.
 
 Guide: https://agent402.tools/guides/openclaw-model-provider
 
@@ -21,8 +22,7 @@ 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
+`--no-wallet` skips the generation. Holding a credits key already issued? Run
 `AGENT402_CREDITS_KEY=a402_... npx agent402-openclaw setup --write` (key by env,
 or `--credits-key -` on stdin).
 
@@ -57,28 +57,31 @@ 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.
+  `max_tokens`) 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
+  what the call actually used, 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.
+Credits-key buyers already pay actual usage on metered calls.
 
 ## Models and pricing
 
 `auto` (routed per prompt, flat $0.01/call) plus every id from
 `GET https://agent402.tools/v1/models`. Explicit models are **metered by default**:
 the proxy sends them to the gateway's metered route, where each request is quoted
-from its body (exact-BPE input plus your `max_tokens` at the model's list price,
-times 1.15, from $0.001, capped at $2 per call), so a short call costs a fraction
+from its body (input plus your `max_tokens`, from $0.001, capped at $2 per
+call), so a short call costs a fraction
 of a cent and a long one pays for what it asks. `--flat` (or
 `AGENT402_PRICING=flat`) keeps every model on its flat per-call tier instead.
-Either way OpenClaw's per-token cost fields stay zero; the price is per call. A model sent to the wrong tier is answered with a
-400 naming the right one; nothing is charged. A client-supplied `Idempotency-Key`
-is passed through (an x402 retry with the same key replays the paid answer);
-without one, each call is its own payment.
+Either way OpenClaw's per-token cost fields stay zero; the price is per call. A model sent to another flat
+tier's route is priced at its home tier: the 402 quotes that tier's price, and the paid call is served under
+that tier's caps (the answer says so in `agent402_tier`). The router, grounded and stealth tiers still answer a
+400 naming the right route; nothing is charged. A client-supplied `Idempotency-Key`
+is passed through: on a credits key, a retry with the same key replays the paid
+answer; on a wallet, each forwarded call signs a fresh payment, which the server
+treats as a new purchase. Without a key, each call is its own payment.
 
 The proxy answers native clients on loopback only: requests carrying a browser
 `Origin` header or a non-loopback `Host` are refused, so a web page cannot spend
@@ -86,7 +89,7 @@ the key.
 
 ## Commands
 
-- `agent402-openclaw setup [--credits-key K | --credits-key - (stdin) | AGENT402_CREDITS_KEY env] [--write] [--port N] [--flat]`
+- `agent402-openclaw setup [--credits-key K | --credits-key - (stdin) | AGENT402_CREDITS_KEY env] [--no-wallet] [--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)
@@ -100,11 +103,12 @@ Anthropic Messages wires, embeddings, rerank, images, video, speech,
 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.
+from 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.
+charged and the receipt proves it, a keyed retry on a credits key is not
+debited twice, and uptime and transactions are published from outside
+production.
 
 Zero dependencies. MIT. Maintained by Havok Holdings LLC.

package/cli.js

@@ -90,7 +90,7 @@ async function main() {
       // 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`);
+        out(`no payment method yet: set AGENT402_WALLET_KEY, rerun without --no-wallet to generate a wallet, or rerun with --credits-key a402_... if you hold a credits key`);
       } else {
         const w = await generateWallet();
         if (w) {
@@ -99,9 +99,9 @@ async function main() {
           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_...`);
+          out(`holding a credits key already issued? rerun with --credits-key a402_... instead`);
         } 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`);
+          out(`no payment method yet: install viem + @x402/fetch + @x402/evm and rerun to generate a wallet, set AGENT402_WALLET_KEY, or rerun with --credits-key a402_... if you hold a credits key`);
         }
       }
     }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "agent402",
   "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.",
+  "description": "Agent402 model provider: an auto-routed tier at a flat per-call price and explicit frontier models priced per request, paid in USDC over x402 or with a prepaid credits key. Same key reaches 500+ pay-per-call tools.",
   "activation": {
     "onStartup": true
   },
@@ -49,7 +49,7 @@
   "uiHints": {
     "creditsKey": {
       "label": "Credits key",
-      "help": "Buy by card at https://agent402.tools/credits",
+      "help": "Issued at https://agent402.tools/credits; that page says whether new keys are on sale",
       "sensitive": true
     },
     "walletKey": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent402-openclaw",
-  "version": "0.4.3",
-  "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.",
+  "version": "0.4.5",
+  "description": "OpenClaw model provider for Agent402: an auto-routed tier at a flat per-call price and explicit LLM models priced per request, paid in USDC over x402 or with a prepaid credits key through a local proxy. Zero dependencies; x402 wallet payment is an optional peer.",
   "type": "module",
   "main": "index.js",
   "exports": {

package/proxy.js

@@ -20,6 +20,15 @@
 // own 402->pay retry), which does NOT make two client calls one payment.
 // Streams pass through byte for byte.
 //
+// Refusals: a refused paid call's 402 from an x402 v2 seller carries the whole
+// payment offer in its JSON body (Agent402 mirrors its PAYMENT-REQUIRED header
+// there) beside the refusal's own reason, hint and retry. OpenClaw's model
+// client builds its error message from `error.message`, else from the whole
+// body, so relaying that body put kilobytes of accepts and schemas into the
+// agent's error text in place of the one sentence that says what to fix. Such
+// a body is answered in the OpenAI error shape instead (refusalAsOpenAIError);
+// every other upstream body passes through byte for byte.
+//
 // Loopback only, and browser-hostile on purpose: any web page can POST to
 // 127.0.0.1 with a "simple" no-cors request, and this proxy spends the
 // user's key, so a request carrying an Origin header (browsers always send
@@ -49,6 +58,27 @@ function readBody(req, limit = MAX_BODY) {
   });
 }
 
+// The x402 offer keys a refusal body may carry beside its own fields.
+const OFFER_KEYS = ["x402Version", "resource", "accepts", "extensions"];
+const text = (v) => (typeof v === "string" && v.trim() ? v : null);
+
+/** An upstream error body that carries an x402 offer (a numeric x402Version),
+ *  as an OpenAI-shaped error: the explanation (a problem's detail, else the
+ *  hint, else the error sentence) as error.message, the retry class or reason as
+ *  error.code, the refusal's own fields beside it, and no offer. Null for any
+ *  other body, which the caller relays unchanged. */
+export function refusalAsOpenAIError(status, doc) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc) || typeof doc.x402Version !== "number") return null;
+  const ours = { ...doc };
+  for (const k of OFFER_KEYS) delete ours[k];
+  const { error, ...fields } = ours;
+  const message = text(fields.detail) || text(fields.hint) || text(error) || text(fields.title) || `Agent402 answered HTTP ${status}`;
+  return {
+    error: { message, type: status === 402 ? "payment_required" : "upstream_error", code: text(fields.retry) || text(fields.reason) || null },
+    ...fields,
+  };
+}
+
 const json = (res, status, obj, headers = {}) => {
   res.writeHead(status, { "content-type": "application/json; charset=utf-8", ...headers });
   res.end(JSON.stringify(obj));
@@ -102,7 +132,7 @@ export async function startProxy({ upstream = DEFAULT_UPSTREAM, creditsKey = nul
           return json(res, 400, { error: { message: `Unknown model "${requested}". Use "auto" or an id from GET /v1/models (${table.size} available).`, type: "invalid_request_error", code: "model_not_found" } });
         }
         if (!paid) {
-          return json(res, 402, { error: { message: "No payment method configured. Set AGENT402_CREDITS_KEY (buy a pack by card at agent402.tools/credits) or configure an x402 wallet (agent402-openclaw setup --wallet).", type: "payment_required", code: "agent402_unconfigured" }, topup: `${upstream}/credits`, priceUsd: route.priceUsd });
+          return json(res, 402, { error: { message: "No payment method configured. Run `agent402-openclaw setup` to generate an x402 wallet, set AGENT402_WALLET_KEY, or set AGENT402_CREDITS_KEY to a credits key already issued.", type: "payment_required", code: "agent402_unconfigured" }, topup: `${upstream}/credits`, priceUsd: route.priceUsd });
         }
         const outbound = { ...body };
         if (requested === AUTO_ID) delete outbound.model; else outbound.model = route.id;
@@ -113,6 +143,18 @@ export async function startProxy({ upstream = DEFAULT_UPSTREAM, creditsKey = nul
         stats.forwarded++;
         const passthrough = {};
         for (const h of ["content-type", "x-credits-balance", "payment-receipt", "x-cache", "cache-control"]) { const v = up.headers.get(h); if (v) passthrough[h] = v; }
+        if (!up.ok && /json/i.test(passthrough["content-type"] || "")) {
+          const raw = await up.text();
+          let doc = null;
+          try { doc = JSON.parse(raw); } catch { /* not JSON after all: relayed as sent */ }
+          const mapped = refusalAsOpenAIError(up.status, doc);
+          if (mapped) {
+            const { "content-type": _ct, ...rest } = passthrough;
+            return json(res, up.status, mapped, rest);
+          }
+          res.writeHead(up.status, passthrough);
+          return res.end(raw);
+        }
         res.writeHead(up.status, passthrough);
         if (!up.body) return res.end();
         const reader = up.body.getReader();