openzoo 0.51.3 → 0.51.5

package/README.md

@@ -25,6 +25,8 @@ paid $0.002137 (9.5× cheaper than direct) · rail solana · tx 5Kd…
 
 **Claude Code / grokui Auto** — `openzoo claude` sets the Anthropic API key + base URL to the local OpenZoo proxy (x402 pay-per-call). You do **not** need to authenticate Claude first. grokui orange Auto is this harness, not a `RUN:` text parser. PATH `~/.local/bin` is required on Mac so `claude` is found.
 
+**ChatGPT desktop (official Linux/macOS/Windows app)** — `openzoo chatgpt` puts the zoo in as the Codex provider in `~/.codex/config.toml`, starts a proxy if none is up, and launches the app; choose **sign in with API key** (any key) and the Codex / agent side pays x402 per turn. The plain ChatGPT chat tab still talks to chatgpt.com — it is not API-shaped. On Arch or anything without dpkg, `openzoo chatgpt --deb ~/Downloads/chatgpt_amd64.deb` unpacks the official .deb into `~/.openzoo/apps/chatgpt` and runs it from there (a `chatgpt*.deb` in `~/Downloads` is found automatically). `--no-launch` writes config only; `--print` shows the block.
+
 **Agent of Empires** (tmux session manager for coding agents, [agent-of-empires](https://github.com/agent-of-empires/agent-of-empires)) — `openzoo aoe` registers an `openzoo` agent in aoe's `config.toml` (`[session.custom_agents] openzoo = "openzoo claude"`, detected as `claude` so status hooks, resume and fork all work), starts a background proxy if none is listening (no public tunnel unless `--tunnel`), then runs `aoe`. `openzoo aoe add . -l` creates and launches one session in the current directory; in the TUI pick **openzoo** from the agent picker. `Alt+z` opens a tool session with the wallet balance and the live receipts log. Terminal view only: aoe's structured view runs `claude-agent-acp` itself, which bills Anthropic, not the zoo. `--override-claude` additionally makes aoe's built-in `claude` agent launch through openzoo; `--no-launch` writes config only.
 
 **Orca** ([stablyai/orca](https://github.com/stablyai/orca), the desktop orchestrator for parallel agents) — Orca launches any CLI agent in a worktree terminal, so type `openzoo claude` as the agent command (or pick **openzoo** from the agent picker once the upstream catalog entry lands). Orca treats it as Claude Code: same process, same hooks and status dots, same `--dangerously-skip-permissions` default. No account switching applies, because nothing is logged in; every turn pays x402.

package/bin/openzoo.js

@@ -146,6 +146,16 @@ usage:
                          voice login / voice watch      PREHOOK your own outgoing Telegram
                                messages: type raw, the watcher revises in place (userbot;
                                "." prefix sends raw). X has no edit API — no equivalent.
+  npx openzoo chatgpt    OpenAI's ChatGPT desktop app on the zoo. Writes the zoo as
+                         the Codex provider in ~/.codex/config.toml (other tables kept,
+                         old file backed up), starts a background proxy if none is up,
+                         and launches the app — the Codex / agent side pays x402 per
+                         turn; pick "sign in with API key" (any key). The plain chat
+                         tab still talks to chatgpt.com.
+                         Arch / no dpkg: --deb ~/Downloads/chatgpt_amd64.deb unpacks it
+                         (a chatgpt*.deb in ~/Downloads is picked up automatically)
+                         --model <id> (claude-opus-5) --wire responses|chat --bearer
+                         --no-launch (config only) --no-proxy --tunnel --print
   npx openzoo openclaw   write the zoo into ~/.openclaw/openclaw.json as a model
                          provider WITH REAL PRICES (OpenClaw's own custom-provider
                          path hard-codes $0.00 and ignores /v1/models pricing)
@@ -169,22 +179,6 @@ usage:
   npx openzoo contexts --forget <hash|all>   drop manifest entries
   npx openzoo balance    wallet balance on every rail — Solana (USDC/TOKEN/SOL),
                          Base (USDC/ETH), Robinhood Chain (USDG/memecoins/ETH)
-  npx openzoo build [dir]     transmute a Vercel-shaped app (Next.js pages/api,
-                              app/**/route, Vite + api/*) for Solana. Default
-                              --target shared: bytecode for the shared zoo-vm
-                              runtime, no Rust toolchain, a site is data accounts
-                              (~0.03-0.1 SOL). --target program: own Pinocchio
-                              program per site (--arch v0|v3, ~1 SOL+)
-  npx openzoo deploy [dir]    deploy the site to Solana accounts (--cluster mainnet,
-                              --runtime <zoo-vm id> or OPENZOO_VM_PROGRAM, --yes to
-                              accept the rent estimate; burner wallet)
-  npx openzoo serve [site]    local gateway/explorer for a deployed site (--runtime,
-                              --cluster, --port 4402); /api/* reads are free
-                              simulations, writes are signed by the burner
-  npx openzoo runtime deploy  deploy the shared zoo-vm runtime once per cluster
-  npx openzoo inspect [dir]   print the app in Vercel terms + eligibility report
-  npx openzoo hub             hosted explorer for every transmuted site on the
-                              cluster (what sites.openzoo.fun runs)
   npx openzoo address    print both funding addresses (Solana + EVM)
   npx openzoo help       this text
 
@@ -232,6 +226,10 @@ async function main() {
       // is enough; no patching of the app bundle.
       await (await import('../lib/grokcli.js')).setupGrokBot(process.argv.slice(3));
       break;
+    case 'chatgpt':
+    case 'codex':
+      await (await import('../lib/chatgpt.js')).setupChatGpt(process.argv.slice(3));
+      break;
     case 'openclaw':
       await (await import('../lib/openclaw.js')).setupOpenClaw(process.argv.slice(3));
       break;
@@ -419,27 +417,6 @@ async function main() {
       if (bal <= 0) console.log('buy some with:  npx openzoo topup 10');
       break;
     }
-    case 'build':
-    case 'deploy':
-    case 'serve':
-    case 'inspect':
-    case 'hub':
-    case 'runtime':
-    case 'transmute': {
-      // VERCEL-SHAPED APP -> SOLANA MAINNET. `openzoo build|deploy|serve` hand
-      // the argv to openzoo-transmute (a sibling npm package): it reads the
-      // app the way `vercel build` would (pages/api, app/**/route, api/*,
-      // .vercel/output), transmutes each Lambda into a Pinocchio Rust program
-      // route, stores the static build in asset accounts, deploys with the
-      // burner wallet at ~/.openzoo/wallet.json, and `serve` runs the local
-      // gateway/explorer that maps http://localhost:4402/... onto the program.
-      const argv = process.argv.slice(2).map((a, i) => (i === 0 && a === 'transmute' ? 'help' : a));
-      // The transmuter ships inside this package (transmute/): lib/cli.js, the
-      // compiler, the gateway + hub and the on-chain runtime crate
-      // (transmute/runtime/zoo-host) all travel with npm — no second install.
-      await (await import('../transmute/lib/cli.js')).run(argv);
-      break;
-    }
     case 'address':
       (await import('../lib/info.js')).printAddress();
       break;

package/lib/chatgpt.js

@@ -0,0 +1,328 @@
+/**
+ * `npx openzoo chatgpt` — OpenAI's ChatGPT desktop app on the zoo.
+ *
+ * The Linux preview of the official app (chatgpt.com/download, August 2026)
+ * ships the Codex engine inside it: `usr/lib/chatgpt/resources/codex`, and
+ * `usr/bin/chatgpt` is a symlink named `codex-launcher`. That engine reads a
+ * standard Codex config — `$CODEX_HOME/config.toml`, default `~/.codex` — and
+ * its `[model_providers.<id>]` table is the supported way to point it at any
+ * OpenAI-shaped server. MEASURED 2026-09-09 on the .deb's `codex` binary:
+ * the strings `model_providers`, `env_key`, `requires_openai_auth`,
+ * `experimental_bearer_token`, `responses` and `https://api.openai.com/v1`
+ * (as a default, next to `ollama` and `amazon-bedrock`) are all there, and
+ * a provider block pointed at :8402 answered in the app.
+ *
+ * What this does and does not redirect, so nobody is surprised:
+ *   - the Codex / agent side of the app ("sign in with API key") → the zoo,
+ *     paid per turn by x402 through the local proxy;
+ *   - the plain ChatGPT conversation tab → still chatgpt.com. It talks to
+ *     `chatgpt_base_url = "https://chatgpt.com/backend-api/"`, a private
+ *     backend that is not API-shaped, so there is nothing to point at us.
+ *   - the two auth modes are exclusive: the binary logs "ChatGPT login is
+ *     required, but an API key is currently being used. Logging out." Pick
+ *     API-key mode for the session that should pay x402.
+ *
+ * One command, end to end: write the provider into config.toml (backing up
+ * the old file, keeping every other table), make sure a proxy is listening,
+ * find the app — or unpack the downloaded .deb on a distro that cannot
+ * install it, which is how this was first done on Arch — and launch it with
+ * the env var the provider's `env_key` names.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { config } from './config.js';
+
+export const PROVIDER_ID = 'openzoo';
+export const API_KEY_ENV = 'OPENZOO_API_KEY';
+export const API_KEY_VALUE = 'sk-openzoo'; // any value: the zoo takes payment, not keys
+
+/** Codex's home: $CODEX_HOME, else ~/.codex. */
+export function codexHome(env = process.env, home = os.homedir()) {
+  return env.CODEX_HOME || path.join(home, '.codex');
+}
+
+export function codexConfigPath(env = process.env, home = os.homedir()) {
+  return path.join(codexHome(env, home), 'config.toml');
+}
+
+export function defaultModel(env = process.env) {
+  // Bare ids are what the doors serve; the gateway resolves the rest.
+  return env.OPENZOO_DEFAULT_MODEL || 'claude-opus-5';
+}
+
+/**
+ * The provider table Codex reads. `wire_api = "responses"` because the local
+ * proxy forwards POST /v1/responses as a paid path (lib/proxy.js) and that is
+ * what Codex speaks natively; `--wire chat` is there for a build that only
+ * does chat completions. `bearer` writes a static token instead of an env
+ * key, for launches this command does not control (a desktop launcher).
+ */
+export function providerBlock({ port = config.port, wireApi = 'responses', bearer = false } = {}) {
+  const lines = [
+    `[model_providers.${PROVIDER_ID}]`,
+    `name = "${PROVIDER_ID}"`,
+    `base_url = "http://localhost:${port}/v1"`,
+    `wire_api = "${wireApi}"`,
+    bearer ? `experimental_bearer_token = "${API_KEY_VALUE}"` : `env_key = "${API_KEY_ENV}"`,
+    'requires_openai_auth = false',
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+const isTableHeader = (line) => /^\s*\[/.test(line);
+const OUR_TABLE = new RegExp(`^\\s*\\[model_providers\\.${PROVIDER_ID}\\]\\s*$`);
+const OUR_MARK = '# written by `npx openzoo chatgpt` — rerun it to refresh, edit freely otherwise';
+
+/**
+ * Merge our provider into an existing config.toml TEXT. Pure.
+ *
+ * TOML puts top-level keys before the first table, so `model` and
+ * `model_provider` are (re)written at the very top and any earlier copies of
+ * those two keys in the top-level span are dropped. Our own table is replaced
+ * wholesale — it is generated, and a stale half-merge is worse than none.
+ * Every other line, table and comment is preserved byte-for-byte. Running
+ * this twice yields identical text.
+ */
+export function mergeCodexConfig(existing, { model, port, wireApi, bearer } = {}) {
+  const src = String(existing || '').replace(/\r\n/g, '\n');
+  const lines = src === '' ? [] : src.split('\n');
+
+  // 1. drop our previous table (header through the line before the next header)
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (OUR_TABLE.test(line)) { skipping = true; continue; }
+    if (skipping && isTableHeader(line)) skipping = false;
+    if (skipping) continue;
+    if (line.trim() === OUR_MARK) continue;
+    kept.push(line);
+  }
+
+  // 2. split into the top-level span and the tables that follow
+  const firstTable = kept.findIndex(isTableHeader);
+  const top = firstTable === -1 ? kept : kept.slice(0, firstTable);
+  const tables = firstTable === -1 ? [] : kept.slice(firstTable);
+
+  // 3. our two keys lead; earlier copies go
+  const ours = new Set(['model', 'model_provider']);
+  const topRest = top.filter((line) => {
+    const m = /^\s*([A-Za-z0-9_-]+)\s*=/.exec(line);
+    return !(m && ours.has(m[1]));
+  });
+  const head = [
+    OUR_MARK,
+    `model = "${model || defaultModel()}"`,
+    `model_provider = "${PROVIDER_ID}"`,
+  ];
+  // trim blank padding so reruns do not accumulate empty lines
+  const trimBlank = (arr) => {
+    const out = [...arr];
+    while (out.length && out[0].trim() === '') out.shift();
+    while (out.length && out[out.length - 1].trim() === '') out.pop();
+    return out;
+  };
+  const parts = [head.join('\n')];
+  const restTop = trimBlank(topRest);
+  if (restTop.length) parts.push(restTop.join('\n'));
+  const restTables = trimBlank(tables);
+  if (restTables.length) parts.push(restTables.join('\n'));
+  parts.push(providerBlock({ port, wireApi, bearer }).trimEnd());
+  return `${parts.join('\n\n')}\n`;
+}
+
+/** Candidate app binaries, most specific first. Exported for tests. */
+export function chatGptCandidates({ env = process.env, home = os.homedir(), platform = process.platform } = {}) {
+  const out = [];
+  if (env.OPENZOO_CHATGPT_BIN) out.push(env.OPENZOO_CHATGPT_BIN);
+  if (platform === 'darwin') {
+    out.push('/Applications/ChatGPT.app/Contents/MacOS/ChatGPT');
+    out.push(path.join(home, 'Applications', 'ChatGPT.app', 'Contents', 'MacOS', 'ChatGPT'));
+  } else if (platform === 'win32') {
+    const local = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    out.push(path.join(local, 'Programs', 'ChatGPT', 'ChatGPT.exe'));
+  } else {
+    // the .deb's layout (apt install), then where THIS command unpacks it,
+    // then the by-hand unpack path the first Arch run used
+    out.push('/usr/lib/chatgpt/ChatGPT');
+    out.push('/opt/ChatGPT/chatgpt');
+    out.push(path.join(unpackDir(home), 'usr', 'lib', 'chatgpt', 'ChatGPT'));
+    out.push(path.join(home, 'apps', 'chatgpt', 'usr', 'lib', 'chatgpt', 'ChatGPT'));
+  }
+  for (const dir of String(env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    out.push(path.join(dir, platform === 'win32' ? 'chatgpt.exe' : 'chatgpt'));
+  }
+  return out;
+}
+
+export function resolveChatGptApp(opts = {}) {
+  const exists = opts.exists || ((p) => { try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; } });
+  return chatGptCandidates(opts).find(exists) || null;
+}
+
+/** Where `--deb` (or an auto-found download) is unpacked. */
+export function unpackDir(home = os.homedir()) {
+  return path.join(home, '.openzoo', 'apps', 'chatgpt');
+}
+
+/** Newest chatgpt*.deb in ~/Downloads, or null. */
+export function findDownloadedDeb(home = os.homedir()) {
+  const dir = path.join(home, 'Downloads');
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return null; }
+  const debs = names
+    .filter((n) => /^chatgpt.*\.deb$/i.test(n))
+    .map((n) => path.join(dir, n))
+    .map((p) => ({ p, t: fs.statSync(p).mtimeMs }))
+    .sort((a, b) => b.t - a.t);
+  return debs.length ? debs[0].p : null;
+}
+
+function have(bin) {
+  return spawnSync(bin, ['--version'], { stdio: 'ignore' }).status !== null;
+}
+
+/**
+ * Unpack a .deb without dpkg: a .deb is an `ar` archive holding data.tar.*.
+ * bsdtar reads both layers; `ar` + `tar` is the fallback. Returns the app
+ * binary path inside `dest`.
+ */
+export function unpackDeb(deb, dest = unpackDir()) {
+  if (!fs.existsSync(deb)) throw new Error(`no such file: ${deb}`);
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(dest, { recursive: true });
+  const outer = fs.mkdtempSync(path.join(os.tmpdir(), 'openzoo-deb-'));
+  const run = (cmd, args, cwd) => {
+    const r = spawnSync(cmd, args, { cwd, stdio: ['ignore', 'ignore', 'pipe'] });
+    if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} failed: ${String(r.stderr || '').trim().slice(0, 200)}`);
+  };
+  if (have('bsdtar')) run('bsdtar', ['-xf', deb], outer);
+  else if (have('ar')) run('ar', ['x', deb], outer);
+  else throw new Error('need bsdtar (libarchive) or ar (binutils) to unpack a .deb');
+  const data = fs.readdirSync(outer).find((n) => /^data\.tar/.test(n));
+  if (!data) throw new Error('not a .deb: no data.tar inside');
+  run('tar', ['-xf', path.join(outer, data), '-C', dest]);
+  fs.rmSync(outer, { recursive: true, force: true });
+  const app = path.join(dest, 'usr', 'lib', 'chatgpt', 'ChatGPT');
+  if (!fs.existsSync(app)) throw new Error(`unpacked, but ${app} is not there — not the ChatGPT .deb?`);
+  return app;
+}
+
+async function ensureProxy({ tunnel }) {
+  const { startProxy, oursOn, packageVersion } = await import('./proxy.js');
+  if (await oursOn(config.port)) return { started: false };
+  // DETACHED, like `openzoo aoe`: the app outlives this command, so the
+  // proxy must too. No public tunnel unless asked — a detached proxy nobody
+  // watches must not open a URL + key that spends the wallet.
+  const logPath = path.join(os.homedir(), '.openzoo', 'proxy.log');
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const fd = fs.openSync(logPath, 'a');
+  const env = { ...process.env };
+  if (!tunnel && !env.OPENZOO_NO_TUNNEL) env.OPENZOO_NO_TUNNEL = '1';
+  const child = spawn(process.execPath, [process.argv[1], 'proxy'], { detached: true, stdio: ['ignore', fd, fd], env });
+  child.unref();
+  fs.closeSync(fd);
+  process.stderr.write(`openzoo: starting the proxy (v${packageVersion()}) in the background, log ${logPath}`);
+  const t0 = Date.now();
+  while (Date.now() - t0 < 60_000) {
+    await new Promise((r) => setTimeout(r, 1000));
+    process.stderr.write('.');
+    try {
+      const r = await fetch(`http://localhost:${config.port}/v1/info`);
+      if (r.ok) { process.stderr.write('\n'); return { started: true, logPath }; }
+    } catch { /* not yet */ }
+  }
+  process.stderr.write('\n');
+  throw new Error(`proxy did not answer on :${config.port} within 60s — see ${logPath}`);
+}
+
+const INSTALL_HELP = `openzoo: ChatGPT desktop app not found.
+  download it from https://chatgpt.com/download (Linux: the .deb; macOS/Windows: the installer), then:
+    Debian/Ubuntu:  sudo apt install ./chatgpt_amd64.deb
+    Fedora:         sudo dnf install ./chatgpt*.rpm
+    Arch / other:   npx openzoo chatgpt --deb ~/Downloads/chatgpt_amd64.deb   (unpacked, no dpkg needed)
+  or point OPENZOO_CHATGPT_BIN at the binary.`;
+
+/**
+ * `npx openzoo chatgpt [--model <id>] [--deb <file>] [--wire responses|chat]
+ *                      [--bearer] [--no-launch] [--no-proxy] [--tunnel] [--print]`
+ */
+export async function setupChatGpt(argv = []) {
+  const args = [...argv];
+  const opt = { model: null, deb: null, wireApi: 'responses', bearer: false, launch: true, proxy: true, tunnel: false, print: false, configPath: null, rest: [] };
+  while (args.length) {
+    const a = args.shift();
+    if (a === '--model') opt.model = String(args.shift() || '').trim() || null;
+    else if (a === '--deb') opt.deb = String(args.shift() || '').trim() || null;
+    else if (a === '--wire') opt.wireApi = String(args.shift() || '').trim();
+    else if (a === '--config') opt.configPath = String(args.shift() || '').trim() || null;
+    else if (a === '--bearer') opt.bearer = true;
+    else if (a === '--no-launch') opt.launch = false;
+    else if (a === '--no-proxy') opt.proxy = false;
+    else if (a === '--tunnel') opt.tunnel = true;
+    else if (a === '--print') opt.print = true;
+    else if (a.startsWith('--')) throw new Error(`unknown flag: ${a}`);
+    else opt.rest.push(a);
+  }
+  if (!['responses', 'chat'].includes(opt.wireApi)) throw new Error('--wire must be responses or chat');
+  const model = opt.model || defaultModel();
+  const merge = { model, port: config.port, wireApi: opt.wireApi, bearer: opt.bearer };
+
+  if (opt.print) {
+    process.stdout.write(mergeCodexConfig('', merge));
+    return { printed: true };
+  }
+
+  // 1. config.toml
+  const file = opt.configPath || codexConfigPath();
+  let existing = '';
+  if (fs.existsSync(file)) {
+    existing = fs.readFileSync(file, 'utf8');
+    fs.copyFileSync(file, `${file}.openzoo-backup`);
+  } else {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+  }
+  const next = mergeCodexConfig(existing, merge);
+  if (next !== existing) fs.writeFileSync(file, next);
+  console.log(`${next !== existing ? 'wrote' : 'kept'} ${file}: model_provider = "${PROVIDER_ID}" (http://localhost:${config.port}/v1, ${opt.wireApi}), model = "${model}"`);
+
+  // 2. proxy
+  if (opt.proxy) {
+    const p = await ensureProxy({ tunnel: opt.tunnel });
+    console.log(p.started ? `proxy up on :${config.port} (background)` : `proxy already on :${config.port}`);
+  }
+
+  if (!opt.launch) {
+    console.log(`config only. launch the app with ${API_KEY_ENV}=${API_KEY_VALUE} in its environment and pick "sign in with API key".`);
+    return { file, model, launched: false };
+  }
+
+  // 3. the app
+  let app = resolveChatGptApp();
+  if (!app && process.platform === 'linux') {
+    const deb = opt.deb || findDownloadedDeb();
+    if (deb) {
+      console.log(`unpacking ${deb} into ${unpackDir()} (no dpkg needed)`);
+      app = unpackDeb(deb);
+    }
+  } else if (opt.deb) {
+    app = unpackDeb(opt.deb);
+  }
+  if (!app) {
+    console.error(INSTALL_HELP);
+    process.exitCode = 1;
+    return { file, model, launched: false };
+  }
+
+  // 4. launch, with the env var the provider's env_key names
+  const env = { ...process.env, [API_KEY_ENV]: process.env[API_KEY_ENV] || API_KEY_VALUE };
+  if (!env.CODEX_HOME) env.CODEX_HOME = codexHome();
+  console.log(`launching ${app}`);
+  console.log(`  Codex / agent mode → the zoo, paid per turn by x402. Choose "sign in with API key" (any key).`);
+  console.log('  the plain ChatGPT chat tab still talks to chatgpt.com — that half is not API-shaped.');
+  const child = spawn(app, opt.rest, { stdio: 'ignore', env, detached: true });
+  child.on('error', (e) => console.error(`openzoo: could not launch ${app}: ${e.message}`));
+  child.unref();
+  return { file, model, app, launched: true };
+}

package/lib/config.js

@@ -80,6 +80,40 @@ export const EVM_FUNDING_ASSETS = {
   ],
 };
 
+/**
+ * RPC endpoint BY CHAIN ID — the only lookup a 402 row can be resolved with.
+ *
+ * A row names its chain as `eip155:<id>` and nothing else. The rail NAMES
+ * above are a coarser bucket: railOf() collapses every chain that is not Base
+ * or Robinhood into the single name "evm", so a lookup keyed by rail name
+ * cannot tell Polygon from Arbitrum and answers with whatever the fallback
+ * branch happens to be.
+ *
+ * MEASURED 2026-09-09: the payment preflight did exactly that — for any
+ * non-Base EVM row it read the balance over the ROBINHOOD RPC, asked a Polygon
+ * USDC address that is not a contract there, threw, was swallowed by the
+ * preflight's catch, and signed an authorization for a chain the wallet held
+ * nothing on. The facilitator then reverted it and the caller was told
+ * "execution reverted" while 76 USDC sat on Base. Keyed by chain id, that
+ * cannot happen: either we can read the chain, or we say we cannot.
+ */
+export const EVM_RPC_BY_CHAIN = {
+  8453: () => config.baseRpcUrl,
+  4663: () => config.rhRpcUrl,
+  137: () => process.env.OPENZOO_POLYGON_RPC || 'https://polygon-rpc.com',
+  42161: () => process.env.OPENZOO_ARBITRUM_RPC || 'https://arb1.arbitrum.io/rpc',
+  10: () => process.env.OPENZOO_OPTIMISM_RPC || 'https://mainnet.optimism.io',
+  480: () => process.env.OPENZOO_WORLD_RPC || 'https://worldchain-mainnet.gateway.tenderly.co',
+};
+
+/** RPC for a row's `eip155:<id>` network, or null when we cannot read that chain. */
+export function evmRpcForNetwork(network) {
+  const m = /^eip155:(\d+)$/.exec(String(network || ''));
+  if (!m) return null;
+  const f = EVM_RPC_BY_CHAIN[Number(m[1])];
+  return f ? f() : null;
+}
+
 /** RPC endpoint for an EVM rail name. */
 export function evmRpcFor(rail) {
   // A rail with no RPC here reports NO balance at all — silently. Every entry

package/lib/pay.js

@@ -1,5 +1,5 @@
 import { Connection } from '@solana/web3.js';
-import { config, fundingLine, evmRpcFor } from './config.js';
+import { config, fundingLine, evmRpcFor, evmRpcForNetwork } from './config.js';
 import { loadOrCreateWallet } from './wallet.js';
 import {
   parse402, orderAccepts, railOf, buildPaymentOnline, tokenBalance,
@@ -123,6 +123,30 @@ const RAIL_MEMO_MS = Number(process.env.OPENZOO_RAIL_MEMO_MS || 15_000);
 const underfundedUntil = new Map();   // asset -> epoch ms after which to re-try it
 let lastGoodAsset = null;
 
+/**
+ * One line to stderr about which rail was chosen or skipped. Quiet by default
+ * would defeat the point — this is the answer to "why did my deposit not get
+ * used", and it is only printed when a rail was actually passed over, so a
+ * normal single-rail call stays silent. OPENZOO_QUIET=1 turns it off.
+ */
+function railNote(msg) {
+  if (process.env.OPENZOO_QUIET === '1') return;
+  try { process.stderr.write(`openzoo: ${msg}\n`); } catch { /* stderr closed */ }
+}
+
+/** "Base (eip155:8453)" — the name a human knows plus the id a log needs. */
+function railLabel(accept) {
+  const n = chainName(accept?.network);
+  return n === accept?.network ? String(n) : `${n} (${accept.network})`;
+}
+
+/** A chain a human recognises, for funding instructions. */
+const CHAIN_NAMES = { 1: 'Ethereum', 10: 'Optimism', 137: 'Polygon', 480: 'World Chain', 4663: 'Robinhood Chain', 8453: 'Base', 42161: 'Arbitrum' };
+export function chainName(network) {
+  const m = /^eip155:(\d+)$/.exec(String(network || ''));
+  return (m && CHAIN_NAMES[Number(m[1])]) || network;
+}
+
 const memoKey = (a) => `${a?.network || ''}|${a?.asset || ''}`;
 
 /** lastGood first, known-underfunded last (never dropped — only deprioritised). */
@@ -197,8 +221,12 @@ export class PayClient {
       const b = await tokenBalance(this.connection, this.keypair.publicKey, accept.asset);
       return BigInt(b.raw || 0);
     }
+    // By chain id, for the reason spelled out in buildPaymentFor: the rail name
+    // cannot tell one non-Base EVM chain from another.
+    const rpcUrl = evmRpcForNetwork(accept.network) ?? evmRpcFor(rail);
+    if (!rpcUrl) return 0n;
     const raw = await evmTokenBalance({
-      rpcUrl: evmRpcFor(rail), token: accept.asset, owner: this.evmAddress,
+      rpcUrl, token: accept.asset, owner: this.evmAddress,
     });
     return BigInt(raw || 0);
   }
@@ -253,8 +281,26 @@ export class PayClient {
       // Preflight: check the settlement-asset balance so an unfundable payment
       // fails HERE with funding instructions instead of at the facilitator.
       // Advisory only — an unreachable RPC never blocks a payment attempt.
-      const rpcUrl = rail === 'base' ? config.baseRpcUrl : config.rhRpcUrl;
+      //
+      // THE RPC IS CHOSEN BY THE ROW'S CHAIN ID, NEVER BY ITS RAIL NAME.
+      // railOf() calls every chain that is not Base or Robinhood "evm", so the
+      // old `rail === 'base' ? baseRpc : rhRpc` sent a POLYGON row's balance
+      // read to Robinhood Chain, where that token address is not a contract.
+      // The read threw, the catch below swallowed it, and this signed an
+      // authorization for a chain holding nothing — the facilitator reverted
+      // it and the caller was told "execution reverted" with a funded Base
+      // wallet one row away. MEASURED 2026-09-09.
+      const rpcUrl = evmRpcForNetwork(accept.network);
       const owner = this.evmAddress;
+      // A CHAIN WE CANNOT READ IS NOT A CHAIN WE SIGN FOR. Skipping the row
+      // costs a caller nothing — the walk moves to the next one and reports
+      // honestly if none is payable — while signing it blind spends the call
+      // on a revert and teaches the caller nothing about why.
+      if (owner && !rpcUrl) {
+        throw new UnderfundedError(accept, null, owner, {
+          line: `No RPC configured for ${accept.network}, so this wallet's balance there cannot be checked — skipping that rail rather than signing blind. Set OPENZOO_POLYGON_RPC (or the matching chain's RPC) to use it.`,
+        });
+      }
       if (owner) {
         const bal = await evmTokenBalance({ rpcUrl, token: accept.asset, owner }).catch(() => null);
         if (bal !== null && bal < BigInt(accept.maxAmountRequired)) {
@@ -263,7 +309,7 @@ export class PayClient {
           // Paxos USDG, which implements EIP-3009 directly, so the only
           // question left on every EVM rail is whether the wallet holds enough.
           const sym = accept?.extra?.symbol || 'the quoted asset';
-          const where = rail === 'robinhood' ? 'Robinhood Chain' : rail === 'base' ? 'Base' : accept.network;
+          const where = rail === 'robinhood' ? 'Robinhood Chain' : rail === 'base' ? 'Base' : chainName(accept.network);
           throw new UnderfundedError(accept, null, owner, {
             line: await withOnrampLink(
               `Send a few cents of ${sym} on ${where} to ${owner}.`,
@@ -340,6 +386,7 @@ export class PayClient {
       }
       try {
         payment = await this.buildPaymentFor(cand, onStage, quote);
+        if (fundErrs.length) railNote(`paying on ${railLabel(cand)}`);
         accept = cand;
         lastGoodAsset = memoKey(cand);
         underfundedUntil.delete(memoKey(cand));
@@ -352,6 +399,15 @@ export class PayClient {
         // Remember it so the next call does not re-pay the discovery cost.
         underfundedUntil.set(memoKey(cand), Date.now() + RAIL_MEMO_MS);
         fundErrs.push({ sym: cand?.extra?.symbol || cand?.asset, err: e });
+        // SAY WHICH RAIL WAS PASSED OVER AND WHY.
+        //
+        // A caller whose wallet is funded on one chain and empty on five
+        // others sees only the LAST row's failure, and the chain that failed
+        // is not the chain they funded. Reading that as "my deposit is not
+        // seen" is the correct reading of what they were shown — the walk was
+        // silent about the five it skipped. One line per skip, on stderr,
+        // makes the choice inspectable without a flag or a debug build.
+        railNote(`skipping ${railLabel(cand)} — ${e.message.replace(/^openzoo wallet underfunded: /, '')}`);
       }
     }
     if (!payment) {

package/lib/proxy.js

@@ -9,7 +9,7 @@ import {
 } from './config.js';
 import { execSync } from 'node:child_process';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
-import { withOnrampLink, settleFailCopy, isFundInstruction } from './stripeOnramp.js';
+import { withOnrampLink, settleFailCopy } from './stripeOnramp.js';
 import { tokenBalance } from './x402.js';
 import { evmTokenBalance } from './evm.js';
 import { autoContext } from './autobind.js';
@@ -1023,11 +1023,12 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         // gateway itself named insufficient_funds. UnderfundedError (empty
         // wallet preflight) is handled in the catch below.
         let msg = copy.message;
-        const wantOnramp = copy.code === 'insufficient_funds'
-          || (!paid && isFundInstruction(copy.reason, copy));
-        if (wantOnramp) {
-          msg = await withOnrampLink(msg, { solana: client.address, usd, code: copy.code });
-        }
+        // EVERY PAYMENT FAILURE ENDS WITH HOW TO PAY. A caller staring at a
+        // facilitator's wording ("execution reverted", "authorization value
+        // mismatch") has exactly three moves — card via Whop, USDC on Solana,
+        // USDC on Base — so every 402 after a payment carries all three, not
+        // only the ones the gateway managed to classify as insufficient funds.
+        msg = await withOnrampLink(msg, { solana: client.address, evm: client.evmAddress, usd, code: copy.code, force: true });
         log(/ties to your account/i.test(msg) ? 'onramp: whop + copy-paste solana' : `402: ${msg.slice(0, 140)}`);
         jsonErr(res, paid ? copy.status : 402, msg);
         return;
@@ -1039,7 +1040,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         jsonErr(res, 402, err.message, { quote: err.quote });
       } else if (err instanceof UnderfundedError) {
         const msg = await withOnrampLink(err.message, {
-          solana: client.address, usd: Number(err.accept?.extra?.billedUsd),
+          solana: client.address, evm: client.evmAddress, usd: Number(err.accept?.extra?.billedUsd),
         });
         log(msg);
         jsonErr(res, 402, msg);

package/lib/stripeOnramp.js

@@ -91,15 +91,21 @@ export function whopBuyUrl() {
   return String(process.env.OPENZOO_WHOP_CHECKOUT || process.env.OPENZOO_WHOP_URL || DEFAULT_WHOP_CHECKOUT).trim();
 }
 
-export function whopFundBlurb(solana) {
+export function whopFundBlurb(solana, evm) {
   const addr = String(solana || '').trim();
   if (!addr) return '';
   const url = whopBuyUrl();
+  const base = String(evm || '').trim();
   return [
     `Hey — buy this: ${url}`,
     '',
     'Copy-paste THIS Solana address into "what is your Solana address?" so it ties to your account:',
     addr,
+    // OR FUND THE WALLET DIRECTLY. Every failed payment ends here: card via
+    // Whop, or USDC to either address — those are the only three moves a
+    // stuck caller has, so they are the whole message.
+    '',
+    `Or send USDC directly — Solana: ${addr}${base ? `  ·  Base: ${base}` : ''}`,
   ].join('\n');
 }
 
@@ -154,8 +160,8 @@ export function settleFailCopy(q402) {
 
 export async function withOnrampLink(text, dest) {
   const body = String(text || '').trim();
-  if (!isFundInstruction(body, dest)) return body;
-  const blurb = whopFundBlurb(dest?.solana);
+  if (!dest?.force && !isFundInstruction(body, dest)) return body;
+  const blurb = whopFundBlurb(dest?.solana, dest?.evm);
   if (!blurb) return body;
   if (/ties to your account/i.test(body) && body.includes(String(dest.solana))) return body;
   return `${blurb}\n\n${body}`;