agent402-openclaw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Havok Holdings LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# agent402-openclaw
+
+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.
+
+Guide: https://agent402.tools/guides/openclaw-model-provider
+
+## Install
+
+```bash
+openclaw plugins install agent402-openclaw
+agent402-openclaw setup --credits-key a402_...   # buy a pack by card at https://agent402.tools/credits
+openclaw gateway restart
+```
+
+`setup` stores the key under `~/.openclaw/agent402/credits.key` (0600) and prints
+the `openclaw.json` block; add `--write` to merge it in (`agent402/auto` becomes
+the primary model). The plugin starts a loopback proxy (`127.0.0.1:8412`) that
+pays Agent402 and forwards; OpenClaw only ever sees a local OpenAI-compatible URL.
+
+No OpenClaw? `agent402-openclaw proxy` runs the proxy alone; point any OpenAI
+client at `http://127.0.0.1:8412/v1` with model `auto`.
+
+## Pay from a wallet instead
+
+```bash
+npm i @x402/fetch @x402/evm viem
+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.
+
+## Models
+
+`auto` (routed per prompt) plus every id from `GET https://agent402.tools/v1/models`,
+each routed to its home tier. Prices are per call, not per token, so OpenClaw's
+per-token cost fields are zero. A model sent to the wrong tier is answered with a
+400 naming the right one; nothing is charged. Every forwarded call carries an
+`Idempotency-Key`, so retries replay the paid answer instead of paying twice.
+
+## Commands
+
+- `agent402-openclaw setup [--credits-key K] [--write] [--port N]`
+- `agent402-openclaw proxy [--port N] [--upstream URL]`
+- `agent402-openclaw doctor`
+
+Zero dependencies. MIT. Maintained by Havok Holdings LLC.

package/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// agent402-openclaw <command>
+//   setup [--credits-key a402_...] [--write]   store the key, print (or merge) the openclaw.json block
+//   proxy [--port N] [--upstream URL]          run the local proxy on its own (no OpenClaw needed)
+//   doctor                                     show what is configured and whether the gateway answers
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { STATE_DIR, CREDITS_KEY_FILE, resolveCreditsKey, resolvePayFetch } from "./index.js";
+import { startProxy, loadRoutes, DEFAULT_UPSTREAM } from "./proxy.js";
+import { providerModelsConfig, stripTrailingSlashes } from "./models.js";
+import { DEFAULT_PORT, PROVIDER_ID } from "./provider.js";
+
+const args = process.argv.slice(2);
+const cmd = args[0] || "help";
+const opt = (k) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : null; };
+const has = (k) => args.includes(k);
+const out = (s) => process.stdout.write(s + "\n");
+
+/** The provider block for openclaw.json (JSON, so it can be merged; OpenClaw reads JSON5 which is a superset). */
+export function configBlock({ port = DEFAULT_PORT, routes }) {
+  return {
+    agents: { defaults: { model: { primary: `${PROVIDER_ID}/auto` } } },
+    models: { providers: { [PROVIDER_ID]: { ...providerModelsConfig(`http://127.0.0.1:${port}`, routes), timeoutSeconds: 120 } } },
+  };
+}
+
+function mergeInto(target, block) {
+  const t = target && typeof target === "object" ? target : {};
+  t.agents = t.agents || {}; t.agents.defaults = t.agents.defaults || {};
+  t.agents.defaults.model = { ...(t.agents.defaults.model || {}), primary: block.agents.defaults.model.primary };
+  t.models = t.models || {}; t.models.providers = t.models.providers || {};
+  t.models.providers[PROVIDER_ID] = block.models.providers[PROVIDER_ID];
+  return t;
+}
+
+async function main() {
+  if (cmd === "help" || has("--help")) {
+    out("agent402-openclaw setup [--credits-key a402_...] [--write] | proxy [--port N] [--upstream URL] | doctor");
+    return 0;
+  }
+  const upstream = stripTrailingSlashes(opt("--upstream") || process.env.AGENT402_UPSTREAM || DEFAULT_UPSTREAM);
+  const port = Number(opt("--port")) || DEFAULT_PORT;
+
+  if (cmd === "setup") {
+    const key = (opt("--credits-key") || "").trim();
+    if (key) {
+      if (!/^a402_[A-Za-z0-9_-]{16,80}$/.test(key)) { console.error("that does not look like an Agent402 credits key (a402_...)"); return 2; }
+      mkdirSync(STATE_DIR(), { recursive: true });
+      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_...`);
+    }
+    let routes;
+    try { routes = await loadRoutes(upstream); } catch (e) { console.error(`could not read ${upstream}/v1/models: ${e?.message || e}`); return 2; }
+    const block = configBlock({ port, routes });
+    const cfgPath = join(process.env.AGENT402_OPENCLAW_HOME || join(homedir(), ".openclaw"), "openclaw.json");
+    if (has("--write")) {
+      let existing = {};
+      if (existsSync(cfgPath)) {
+        try { existing = JSON.parse(readFileSync(cfgPath, "utf8")); }
+        catch { console.error(`${cfgPath} is not plain JSON (JSON5 comments?); not touching it. Merge this block by hand:`); out(JSON.stringify(block, null, 2)); return 2; }
+      }
+      mkdirSync(join(cfgPath, ".."), { recursive: true });
+      const tmp = `${cfgPath}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(mergeInto(existing, block), null, 2) + "\n");
+      const { renameSync } = await import("node:fs"); renameSync(tmp, cfgPath);
+      out(`wrote provider "${PROVIDER_ID}" + primary model ${PROVIDER_ID}/auto into ${cfgPath}; run: openclaw gateway restart`);
+    } else {
+      out(`add to ${cfgPath} (or rerun with --write):`);
+      out(JSON.stringify(block, null, 2));
+    }
+    return 0;
+  }
+
+  if (cmd === "proxy") {
+    const creditsKey = resolveCreditsKey();
+    const payFetch = creditsKey ? null : await resolvePayFetch({}, (m) => console.error(m));
+    const p = await startProxy({ upstream, creditsKey, payFetch, port, log: (m) => console.error(m) });
+    out(`${p.baseUrl}/v1 (${p.mode})`);
+    await new Promise(() => {}); // run until killed
+  }
+
+  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"}`);
+    try { const r = await loadRoutes(upstream); out(`gateway: ok, ${r.size} models`); } catch (e) { out(`gateway: unreachable (${e?.message || e})`); return 1; }
+    if (key) {
+      try {
+        const r = await fetch(`${upstream}/api/credits/balance`, { headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(15_000) });
+        const j = await r.json().catch(() => ({}));
+        out(`balance: ${r.ok ? `$${j.balanceUsd ?? j.balance ?? "?"}` : `HTTP ${r.status} ${j.reason || j.error || ""}`}`);
+      } catch (e) { out(`balance: unreadable (${e?.message || e})`); }
+    }
+    return 0;
+  }
+
+  console.error(`unknown command: ${cmd}`); return 2;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().then((c) => process.exit(c ?? 0), (e) => { console.error(e?.message || e); process.exit(1); });
+}

package/index.js

@@ -0,0 +1,76 @@
+// OpenClaw plugin entry (listed in package.json "openclaw.extensions").
+// register() is what OpenClaw's loader calls - several times per gateway start
+// (discovery, activation, per session), so registration is idempotent and the
+// proxy is started once as a plugin service.
+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 { 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");
+
+/** Credits key precedence: plugin config > env > ~/.openclaw/agent402/credits.key. */
+export function resolveCreditsKey(pluginConfig = {}) {
+  const fromCfg = typeof pluginConfig.creditsKey === "string" ? pluginConfig.creditsKey.trim() : "";
+  if (fromCfg) return fromCfg;
+  const fromEnv = (process.env.AGENT402_CREDITS_KEY || "").trim();
+  if (fromEnv) return fromEnv;
+  try { if (existsSync(CREDITS_KEY_FILE())) return readFileSync(CREDITS_KEY_FILE(), "utf8").trim(); } catch { /* unreadable */ }
+  return null;
+}
+
+/** Optional x402 wallet payment: only when the peer deps are installed and a key is present. */
+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);
+  } 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;
+  }
+}
+
+let started = null;
+let registeredOnce = false;
+
+const plugin = {
+  id: PROVIDER_ID,
+  name: "Agent402",
+  description: "Agent402 model provider: routed + explicit models at a flat per-call price, paid by card or USDC.",
+  register(api) {
+    const cfg = api.pluginConfig || {};
+    const port = Number(cfg.port) || DEFAULT_PORT;
+    const upstream = stripTrailingSlashes(cfg.upstream || process.env.AGENT402_UPSTREAM || DEFAULT_UPSTREAM);
+    const log = (m) => api.logger?.info?.(m);
+    api.registerProvider(buildProvider({ port }));
+    if (!registeredOnce) {
+      registeredOnce = true;
+      api.registerService({
+        id: "agent402-proxy",
+        start: async () => {
+          if (started) return;
+          const creditsKey = resolveCreditsKey(cfg);
+          const payFetch = creditsKey ? null : await resolvePayFetch(cfg, log);
+          try { setCachedRoutes(await loadRoutes(upstream)); } catch (e) { log(`[agent402-openclaw] could not read ${upstream}/v1/models yet: ${e?.message || e}`); }
+          started = await startProxy({ upstream, creditsKey, payFetch, port, log });
+          setActiveProxy(started);
+          if (started.mode === "unpaid") log("[agent402-openclaw] no payment configured: run `agent402-openclaw setup` (card credits key) - paid calls will answer 402 until then");
+        },
+        stop: async () => { if (started) { await started.close(); started = null; setActiveProxy(null); } },
+      });
+    }
+  },
+};
+
+export default plugin;
+export { plugin, buildProvider, startProxy };

package/models.js

@@ -0,0 +1,71 @@
+// Model list for OpenClaw, built from the gateway's own GET /v1/models so the
+// plugin never carries a hand-typed catalog (a stale id would be a paid 502
+// for the user). "auto" is always first: it is the routed tier and the
+// recommended primary. Every other entry is an explicit model id with the
+// tier's flat per-call price in its display name, because OpenClaw's cost
+// fields are per token and Agent402 bills per call - those stay at zero so
+// the UI never shows a made-up per-token figure.
+
+export const AUTO_ID = "auto";
+
+/** Linear trailing-slash strip (a regex like /\/+$/ is polynomial on long runs of "/"). */
+export function stripTrailingSlashes(s) {
+  let str = String(s ?? ""); let end = str.length;
+  while (end > 0 && str.charCodeAt(end - 1) === 47) end--;
+  return str.slice(0, end);
+}
+
+
+/** The raw catalog entry -> { id, endpoint, tier, priceUsd, maxTokens, maxInputChars }. */
+export function routesFromCatalog(catalog) {
+  const data = Array.isArray(catalog?.data) ? catalog.data : [];
+  const routes = new Map();
+  for (const m of data) {
+    const x = m?.x402;
+    if (!m?.id || !x?.endpoint || typeof x.priceUsd !== "number") continue;
+    if (String(m.id).endsWith("*")) continue; // family wildcard, not an id
+    routes.set(m.id, {
+      id: m.id,
+      endpoint: x.endpoint,
+      tier: x.tier || null,
+      priceUsd: x.priceUsd,
+      maxTokens: Number(x.maxTokens) || 1024,
+      maxInputChars: Number(x.maxInputChars) || 32_000,
+      stealth: !!x.stealth,
+    });
+  }
+  // The routed tier accepts a bare "auto" (model optional); expose it under
+  // that id whatever the catalog lists for the tier's own prefixes.
+  const autoRow = data.find((m) => m?.x402?.tier === "v1-chat-auto");
+  if (autoRow) {
+    routes.set(AUTO_ID, {
+      id: AUTO_ID, endpoint: autoRow.x402.endpoint, tier: "v1-chat-auto",
+      priceUsd: autoRow.x402.priceUsd, maxTokens: Number(autoRow.x402.maxTokens) || 1024,
+      maxInputChars: Number(autoRow.x402.maxInputChars) || 32_000, stealth: false,
+    });
+  }
+  return routes;
+}
+
+const priceLabel = (usd) => (usd < 0.01 ? `$${usd.toFixed(3)}` : `$${usd.toFixed(2)}`);
+
+/** OpenClaw `models[]` entries for a provider block. `auto` first. */
+export function openclawModels(routes) {
+  const rows = [...routes.values()].filter((r) => !r.stealth);
+  rows.sort((a, b) => (a.id === AUTO_ID ? -1 : b.id === AUTO_ID ? 1 : a.priceUsd - b.priceUsd || a.id.localeCompare(b.id)));
+  return rows.map((r) => ({
+    id: r.id,
+    name: r.id === AUTO_ID ? `Agent402 auto (routed, ${priceLabel(r.priceUsd)}/call)` : `${r.id} (${priceLabel(r.priceUsd)}/call)`,
+    reasoning: false,
+    input: ["text"],
+    // Flat per-call billing: OpenClaw's per-token cost display does not apply.
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: Math.min(Math.floor(r.maxInputChars / 4), 128_000),
+    maxTokens: r.maxTokens,
+  }));
+}
+
+/** OpenClaw ModelProviderConfig pointing at the local proxy. */
+export function providerModelsConfig(baseUrl, routes) {
+  return { baseUrl: `${stripTrailingSlashes(baseUrl)}/v1`, api: "openai-completions", models: openclawModels(routes) };
+}

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "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.",
+  "activation": {
+    "onStartup": true
+  },
+  "enabledByDefault": true,
+  "providers": ["agent402"]
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "agent402-openclaw",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./index.js",
+    "./proxy": "./proxy.js",
+    "./models": "./models.js"
+  },
+  "bin": {
+    "agent402-openclaw": "cli.js"
+  },
+  "files": [
+    "index.js",
+    "provider.js",
+    "models.js",
+    "proxy.js",
+    "cli.js",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "peerDependencies": {
+    "@x402/evm": ">=2.20.0",
+    "@x402/fetch": ">=2.20.0"
+  },
+  "peerDependenciesMeta": {
+    "@x402/evm": {
+      "optional": true
+    },
+    "@x402/fetch": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "llm-router",
+    "x402",
+    "mpp",
+    "ai-agents",
+    "usdc",
+    "agent402"
+  ],
+  "author": "Havok Holdings LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MikeyPetrillo/Agent402.git",
+    "directory": "openclaw"
+  },
+  "homepage": "https://agent402.tools/guides/openclaw-model-provider"
+}

package/provider.js

@@ -0,0 +1,35 @@
+// The OpenClaw ProviderPlugin. Its `models` getter always points at the local
+// proxy URL - the configured port before the proxy is up, the live one after -
+// so OpenClaw persists a loopback baseUrl and never the remote gateway (which
+// would 402 without the proxy's payment step in between).
+import { providerModelsConfig, routesFromCatalog } from "./models.js";
+
+export const PROVIDER_ID = "agent402";
+export const DEFAULT_PORT = 8412;
+
+let activeProxy = null;
+let cachedRoutes = null;
+export function setActiveProxy(p) { activeProxy = p; }
+export function getActiveProxy() { return activeProxy; }
+export function setCachedRoutes(r) { cachedRoutes = r; }
+
+/** Minimal offline route table so the provider registers even before /v1/models is read. */
+export const BOOTSTRAP_ROUTES = routesFromCatalog({ data: [
+  { id: "auto", x402: { tier: "v1-chat-auto", endpoint: "/v1/auto/chat/completions", priceUsd: 0.01, maxTokens: 1024, maxInputChars: 32_000 } },
+] });
+
+export function buildProvider({ port = DEFAULT_PORT } = {}) {
+  return {
+    id: PROVIDER_ID,
+    label: "Agent402",
+    docsPath: "https://agent402.tools/guides/openclaw-model-provider",
+    aliases: ["a402"],
+    envVars: ["AGENT402_CREDITS_KEY", "AGENT402_WALLET_KEY"],
+    get models() {
+      const base = activeProxy ? activeProxy.baseUrl : `http://127.0.0.1:${port}`;
+      return providerModelsConfig(base, cachedRoutes || BOOTSTRAP_ROUTES);
+    },
+    // No provider auth: the proxy carries the credits key or signs the payment.
+    auth: [],
+  };
+}

package/proxy.js

@@ -0,0 +1,122 @@
+// Local OpenAI-compatible proxy: OpenClaw (or any client) talks to
+// http://127.0.0.1:<port>/v1, the proxy pays Agent402 and forwards.
+//
+// Two ways to pay, chosen at start:
+//   creditsKey  - a prepaid card-credits key (a402_...) sent as a Bearer; the
+//                 gateway authorizes against the balance before the handler and
+//                 debits only on a final 200. No wallet, no chain.
+//   payFetch    - an x402-paying fetch (e.g. @x402/fetch wrapped around a
+//                 wallet signer) used for the upstream call; the gateway's 402
+//                 is settled per call in USDC. The proxy never sees a key.
+// With neither, paid calls answer a 402-shaped JSON that says how to set up.
+//
+// Routing: the model id decides the upstream tier endpoint, read from the
+// gateway's own GET /v1/models at start (never a hand-typed table). "auto"
+// goes to the routed tier with the model field omitted.
+//
+// Retries are safe: every forwarded request carries a fresh Idempotency-Key,
+// so a client retry of the same request replays the paid response instead of
+// paying twice. Streams pass through byte for byte.
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { AUTO_ID, routesFromCatalog, stripTrailingSlashes } from "./models.js";
+
+export const DEFAULT_UPSTREAM = "https://agent402.tools";
+const MAX_BODY = 2 * 1024 * 1024;
+
+export async function loadRoutes(upstream, fetchImpl = fetch) {
+  const r = await fetchImpl(`${upstream}/v1/models`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
+  if (!r.ok) throw new Error(`GET /v1/models -> HTTP ${r.status}`);
+  return routesFromCatalog(await r.json());
+}
+
+function readBody(req, limit = MAX_BODY) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let n = 0;
+    req.on("data", (c) => { n += c.length; if (n > limit) { reject(new Error("body too large")); req.destroy(); return; } chunks.push(c); });
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+const json = (res, status, obj, headers = {}) => {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", ...headers });
+  res.end(JSON.stringify(obj));
+};
+
+/**
+ * @param {object} o
+ * @param {string} [o.upstream]      gateway origin (default https://agent402.tools)
+ * @param {string} [o.creditsKey]    prepaid credits key (a402_...)
+ * @param {Function} [o.payFetch]    x402-paying fetch for wallet payment
+ * @param {Function} [o.fetch]       plain fetch (tests inject one)
+ * @param {number} [o.port]          0 = ephemeral
+ * @param {string} [o.host]          default 127.0.0.1 (loopback only: anyone who can reach the port spends your key)
+ * @param {Map} [o.routes]           pre-loaded routes (tests); else loaded from upstream
+ * @param {(msg:string)=>void} [o.log]
+ */
+export async function startProxy({ upstream = DEFAULT_UPSTREAM, creditsKey = null, payFetch = null, fetch: fetchImpl = fetch, port = 0, host = "127.0.0.1", routes = null, log = () => {} } = {}) {
+  upstream = stripTrailingSlashes(upstream);
+  const key = typeof creditsKey === "string" && /^a402_[A-Za-z0-9_-]{16,80}$/.test(creditsKey) ? creditsKey : null;
+  const paid = key ? fetchImpl : payFetch;
+  const mode = key ? "credits" : payFetch ? "x402" : "unpaid";
+  let table = routes || await loadRoutes(upstream, fetchImpl);
+  const stats = { requests: 0, forwarded: 0, errors: 0, startedAt: new Date().toISOString() };
+
+  const server = createServer(async (req, res) => {
+    stats.requests++;
+    const url = new URL(req.url, "http://localhost");
+    try {
+      if (req.method === "GET" && url.pathname === "/health") {
+        return json(res, 200, { ok: true, upstream, mode, models: table.size, stats });
+      }
+      if (req.method === "GET" && url.pathname === "/v1/models") {
+        return json(res, 200, { object: "list", data: [...table.values()].filter((r) => !r.stealth).map((r) => ({ id: r.id, object: "model", owned_by: "agent402", agent402: { endpoint: r.endpoint, priceUsd: r.priceUsd, tier: r.tier } })) });
+      }
+      if (req.method === "POST" && url.pathname === "/v1/chat/completions") {
+        const raw = await readBody(req);
+        let body;
+        try { body = JSON.parse(raw.toString("utf8") || "{}"); } catch { return json(res, 400, { error: { message: "Request body must be JSON", type: "invalid_request_error" } }); }
+        const requested = typeof body.model === "string" && body.model.trim() ? body.model.trim().replace(/^agent402\//, "") : AUTO_ID;
+        const route = table.get(requested);
+        if (!route) {
+          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 });
+        }
+        const outbound = { ...body };
+        if (requested === AUTO_ID) delete outbound.model; else outbound.model = route.id;
+        const headers = { "content-type": "application/json", accept: req.headers.accept || "application/json", "idempotency-key": randomUUID(), "user-agent": "agent402-openclaw/0.1.0" };
+        if (key) headers.authorization = `Bearer ${key}`;
+        const up = await paid(`${upstream}${route.endpoint}`, { method: "POST", headers, body: JSON.stringify(outbound), signal: AbortSignal.timeout(300_000) });
+        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; }
+        res.writeHead(up.status, passthrough);
+        if (!up.body) return res.end();
+        const reader = up.body.getReader();
+        req.on("close", () => { reader.cancel().catch(() => {}); });
+        for (;;) { const { done, value } = await reader.read(); if (done) break; res.write(Buffer.from(value)); }
+        return res.end();
+      }
+      return json(res, 404, { error: { message: `No route for ${req.method} ${url.pathname}`, type: "invalid_request_error" } });
+    } catch (e) {
+      stats.errors++;
+      log(`[agent402-openclaw] ${req.method} ${url.pathname}: ${e?.message || e}`);
+      if (!res.headersSent) return json(res, 502, { error: { message: `Upstream error: ${String(e?.message || e).slice(0, 200)}`, type: "upstream_error" } });
+      try { res.end(); } catch { /* ignore */ }
+    }
+  });
+
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(port, host, resolve); });
+  const actualPort = server.address().port;
+  const baseUrl = `http://${host}:${actualPort}`;
+  log(`[agent402-openclaw] proxy on ${baseUrl}/v1 -> ${upstream} (${mode}, ${table.size} models)`);
+  return {
+    baseUrl, port: actualPort, mode, upstream,
+    stats: () => ({ ...stats }),
+    refreshModels: async () => { table = await loadRoutes(upstream, fetchImpl); return table.size; },
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}