openzoo 0.4.2 → 0.6.0

package/README.md

@@ -126,6 +126,39 @@ npx openzoo contexts --forget all     # drop everything
 
 Opt out with `OPENZOO_NO_CONTEXT_CACHE=1` (always ship the full body); tune the threshold with `OPENZOO_CONTEXT_MIN_CHARS` (default 16384 chars).
 
+## Using openzoo from a cloud IDE (Cursor, Windsurf, hosted agents)
+
+Some IDEs run their model calls **from their own servers**, not your machine. Point one of those at `http://localhost:8402` and you get, verbatim:
+
+```
+Provider returned error: Access to private networks is forbidden
+```
+
+That is reachability, not payment — their cloud cannot dial your laptop. Give it a public URL instead:
+
+```bash
+npx openzoo tunnel
+```
+
+It installs `cloudflared` itself (one-time, cached in `~/.openzoo/bin`; a Cloudflare account is not needed), opens a quick tunnel to your local proxy, and prints:
+
+```
+base_url = https://<random>.trycloudflare.com/v1
+api_key  = oz_<random>          # in tunnel mode the key is REAL auth
+```
+
+**Tunnel mode is the one mode where the api key matters.** A public URL in front of a wallet is a public URL in front of your money, so:
+
+- every request without `Authorization: Bearer <that key>` is refused **401** before anything is forwarded, quoted or paid;
+- the per-call cap (`OPENZOO_MAX_USD_PER_CALL`, default $0.50) still applies;
+- a session ceiling stops all spending at `OPENZOO_TUNNEL_MAX_USD` (default **$1.00**);
+- every served request prints its receipt and the running session total;
+- the URL dies when you Ctrl-C, and the session's total spend is printed on exit.
+
+Pin the key with `OPENZOO_TUNNEL_TOKEN` if your IDE stores it. Keys never leave your machine either way — the tunnel forwards to the same local proxy, which signs with the same local wallet.
+
+**MCP clients don't need any of this.** If your tool speaks MCP, use the hosted server at `https://mcp.openzoo.fun/mcp` — cloud-reachable, no local process, mint a wallet with `zoo_wallet`.
+
 ## The wallet model
 
 - **Burner, local, yours.** A keypair in `~/.openzoo/wallet.json`, created on first run, chmod 600. Keys never leave your machine — the zoo only ever sees signed transfers.
@@ -135,8 +168,9 @@ Opt out with `OPENZOO_NO_CONTEXT_CACHE=1` (always ship the full body); tune the
 
   Both are first-class: each is the underlying of a live Solana rail the zoo quotes (USDC → yUSDCx, TOKEN → wTOKENx). That's the whole funding story — the shim converts whichever the 402 quotes internally, at payment time, for exactly the amount needed.
 - **SOL is optional but nice.** The gateway sponsors payment-transaction fees. If the wallet holds a pinch of SOL (~0.003), the internal conversion settles as its own transaction first; with zero SOL the conversion rides inside the gateway-sponsored payment transaction instead.
+- **The same wallet file also holds an EVM key.** `npx openzoo address` prints both addresses: the Solana one, and the EVM one used by the Base and Robinhood Chain rails. Fund Base with plain **USDC on Base** (nothing is converted); for Robinhood Chain, deposit USDG at [x402.accrue.fund/start](https://x402.accrue.fund/start) so the wallet holds the settlement asset.
 - **Spend caps.** The proxy refuses any single quote above `OPENZOO_MAX_USD_PER_CALL` (default $0.50).
-- `npx openzoo balance` / `npx openzoo address` — check funds (USDC + TOKEN + SOL + USD value) / print the address.
+- `npx openzoo balance` — funds on every rail, grouped per chain: Solana (USDC + TOKEN + SOL), Base (USDC + ETH), Robinhood Chain (USDG, the ODDBALLER / IOU / ROBINHOODS memecoins, ETH). USD value where a price is known; `$?` where not. `npx openzoo address` — both funding addresses.
 
 ## Honest pricing note
 
@@ -149,15 +183,17 @@ The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect`
 
 ## Payment rails
 
+All three rails have settled real payments (2026-08-14):
+
 | rail | network | status |
 |---|---|---|
-| **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Tested end-to-end against the production 402. Settlement uses a wrapped settlement mint as internal plumbing; you only ever hold and send USDC or TOKEN. |
-| Base | `eip155:8453` | **offered by the zoo** — standard x402 EIP-3009 `transferWithAuthorization` against native USDC. Fund the wallet's EVM address with USDC on Base; nothing is converted. Settlement from this package is live-untested. |
-| Robinhood Chain | `eip155:4663` | experimental, behind `OPENZOO_ENABLE_RH=1`. The zoo quotes it, but its settlement asset has no conversion path here (conversion is Solana-only), so there is no plain balance you can fund and have the shim spend — use Solana or Base. |
+| **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Settles daily; tested end-to-end against the production 402. Settlement uses a wrapped settlement mint as internal plumbing; you only ever hold and send USDC or TOKEN. |
+| Base | `eip155:8453` | **live** — standard x402 EIP-3009 `transferWithAuthorization` against native USDC, batched settle through the facilitator. Fund the wallet's EVM address with USDC on Base; nothing is converted. |
+| Robinhood Chain | `eip155:4663` | **live** — EIP-3009 against the RH settlement asset, batched settle through the facilitator. There is no auto-conversion path here (conversion is Solana-only), so the wallet must hold the settlement asset itself: deposit USDG at [x402.accrue.fund/start](https://x402.accrue.fund/start). Default rail selection skips it unless `OPENZOO_ENABLE_RH=1`; `OPENZOO_RAIL=robinhood` forces it outright. |
 
-`npx openzoo` prints the rails off a live 402 at startup, and the funding line is derived from those rails — so a new chain shows up without this package shipping again.
+`npx openzoo` prints the rails off a live 402 at startup, and the funding line is derived from those rails — so a new chain (the wrapped RH memecoin twins are in-deploy, for example) shows up without this package shipping again.
 
-The rail is chosen from the 402's `accepts[]` itself (Solana first). Amounts are always taken as raw units from the 402, and Solana decimals are read from the mint **on-chain** — never hardcoded. (The zoo's own pasted prompt hardcodes `decimals = 6`; that's wrong for 18-decimal mints and this package deliberately does not copy the bug.)
+The rail is chosen from the 402's `accepts[]` itself (Solana first). **Steer it with `OPENZOO_RAIL=solana|base|robinhood`** — the picker then uses only that rail, and errors clearly if the live 402 does not offer it. Amounts are always taken as raw units from the 402, and Solana decimals are read from the mint **on-chain** — never hardcoded. (The zoo's own pasted prompt used to hardcode `decimals = 6`; this package deliberately does not copy the bug.)
 
 ## Configuration
 
@@ -167,12 +203,15 @@ The rail is chosen from the 402's `accepts[]` itself (Solana first). Amounts are
 | `OPENZOO_API_BASE` | `https://x402-tokens.fly.dev` | the zoo's door |
 | `OPENZOO_RPC` | mainnet-beta public RPC | Solana RPC |
 | `OPENZOO_TOKEN` | (internal) | preferred 402 rail — leave unset |
+| `OPENZOO_RAIL` | (unset) | force a rail: `solana` \| `base` \| `robinhood`. Errors if the live 402 doesn't offer it |
+| `OPENZOO_BASE_RPC` | `https://mainnet.base.org` | Base RPC (balances / preflight) |
+| `OPENZOO_RH_RPC` | `https://rpc.mainnet.chain.robinhood.com` | Robinhood Chain RPC (balances / preflight) |
 | `OPENZOO_WALLET` | `~/.openzoo/wallet.json` | wallet path |
 | `OPENZOO_MAX_USD_PER_CALL` | `0.5` | refuse quotes above this |
 | `OPENZOO_DEMO_MAX_USD` | `0.01` | demo spend cap |
 | `OPENZOO_CONTEXT_MIN_CHARS` | `16384` | bodies bigger than this bind once + reuse |
 | `OPENZOO_NO_CONTEXT_CACHE` | `0` | set `1` to always ship the full body |
-| `OPENZOO_ENABLE_RH` | `0` | allow the Robinhood rail |
+| `OPENZOO_ENABLE_RH` | `0` | let default selection fall through to the Robinhood rail (`OPENZOO_RAIL=robinhood` forces it without this) |
 
 ## What's tested
 

package/bin/openzoo.js

@@ -6,25 +6,36 @@ const HELP = `openzoo — local x402-paying proxy + MCP server for openzoo.fun
 usage:
   npx openzoo            start the proxy on http://localhost:8402/v1
   npx openzoo mcp        stdio MCP server (tools: zoo_ask, zoo_models, zoo_wallet)
+  npx openzoo tunnel     public HTTPS url for cloud IDEs that cannot reach localhost
+                         (installs cloudflared itself; mints a required api key)
   npx openzoo demo       ~1M-token needle demo: direct refuses, the zoo answers
                          (run it twice — the second run reuses the bound corpus and is near-free)
   npx openzoo contexts   list corpora bound to the zoo (never re-uploaded)
   npx openzoo contexts --forget <hash|all>   drop manifest entries
-  npx openzoo balance    wallet balance (USDC + TOKEN + SOL, with USD value)
-  npx openzoo address    print the funding address
+  npx openzoo balance    wallet balance on every rail — Solana (USDC/TOKEN/SOL),
+                         Base (USDC/ETH), Robinhood Chain (USDG/memecoins/ETH)
+  npx openzoo address    print both funding addresses (Solana + EVM)
   npx openzoo help       this text
 
 point any OpenAI-compatible harness at:
   base_url = http://localhost:8402/v1
   api_key  = sk-openzoo   (any value; the zoo takes payment, not keys)
 
+rails (all three settle real payments; Solana is the default):
+  OPENZOO_RAIL=solana|base|robinhood forces one rail — errors clearly if the
+  live 402 does not offer it. Unset = Solana first.
+
 env:
   OPENZOO_PORT (8402)  OPENZOO_API_BASE (https://x402-tokens.fly.dev)
   OPENZOO_RPC (mainnet-beta)  OPENZOO_TOKEN (402 rail preference)  OPENZOO_WALLET (~/.openzoo/wallet.json)
+  OPENZOO_RAIL (unset — force a rail: solana | base | robinhood)
+  OPENZOO_BASE_RPC (https://mainnet.base.org)  OPENZOO_RH_RPC (rpc.mainnet.chain.robinhood.com)
   OPENZOO_MAX_USD_PER_CALL (0.5)  OPENZOO_DEMO_MAX_USD (0.01)
   OPENZOO_CONTEXT_MIN_CHARS (16384 — bodies bigger than this bind once + reuse)
   OPENZOO_NO_CONTEXT_CACHE (0 — set 1 to always ship the full body)
-  OPENZOO_ENABLE_RH (0 — Robinhood Chain rail, experimental)`;
+  OPENZOO_ENABLE_RH (0 — let DEFAULT selection fall through to the Robinhood rail;
+                     OPENZOO_RAIL=robinhood forces it without this)
+  OPENZOO_TUNNEL_MAX_USD (1.00 — tunnel session ceiling)  OPENZOO_TUNNEL_TOKEN (pin the api key)`;
 
 async function main() {
   switch (cmd) {
@@ -35,6 +46,9 @@ async function main() {
     case 'mcp':
       await (await import('../lib/mcp.js')).startMcp();
       break;
+    case 'tunnel':
+      await (await import('../lib/tunnel.js')).runTunnel();
+      break;
     case 'demo':
       await (await import('../lib/demo.js')).runDemo();
       break;

package/lib/config.js

@@ -7,6 +7,12 @@ export const config = {
   rpcUrl: process.env.OPENZOO_RPC || 'https://api.mainnet-beta.solana.com',
   // Which accepts[] row to pay with, by extra.symbol (internal rail selector).
   token: process.env.OPENZOO_TOKEN || 'yUSDCx',
+  // Force a rail: 'solana' | 'base' | 'robinhood'. Unset -> Solana-first order.
+  // pickAccept errors clearly when the live 402 does not offer the forced rail.
+  rail: (process.env.OPENZOO_RAIL || '').toLowerCase() || null,
+  // EVM RPCs for balance reads / preflight checks on the Base and RH rails.
+  baseRpcUrl: process.env.OPENZOO_BASE_RPC || 'https://mainnet.base.org',
+  rhRpcUrl: process.env.OPENZOO_RH_RPC || 'https://rpc.mainnet.chain.robinhood.com',
   walletPath: process.env.OPENZOO_WALLET || path.join(os.homedir(), '.openzoo', 'wallet.json'),
   // Refuse to auto-pay any single 402 quote above this many USD (extra.billedUsd).
   maxUsdPerCall: Number(process.env.OPENZOO_MAX_USD_PER_CALL || 0.5),
@@ -28,6 +34,30 @@ export const FUNDING_ASSETS = [
 export const USDC_MINT = FUNDING_ASSETS[0].mint;
 export const TOKEN_MINT = FUNDING_ASSETS[1].mint;
 
+/**
+ * EVM-side balances `openzoo balance` reports, grouped by rail. `usd` is a
+ * known price (stables); null means "no honest price here" and the CLI prints
+ * `?` rather than inventing one. The memecoins are Robinhood Chain ERC-20s
+ * (18 decimals, verified on-chain 2026-08-14); their wrapped x402 twins are
+ * in-deploy and will appear in the 402 itself when live.
+ */
+export const EVM_FUNDING_ASSETS = {
+  base: [
+    { symbol: 'USDC', address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', decimals: 6, usd: 1 },
+  ],
+  robinhood: [
+    { symbol: 'USDG', address: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168', decimals: 6, usd: 1 },
+    { symbol: 'ODDBALLER', address: '0x923eb7BD5B84a1a114CB57212cE2F2e87AE60E2A', decimals: 18, usd: null },
+    { symbol: 'IOU', address: '0xf391999FACbEE613D4024191Dd31060540BF0bEd', decimals: 18, usd: null },
+    { symbol: 'ROBINHOODS', address: '0xC42cF61C16aaC797b991cf9C1ac8Ae70bA74A286', decimals: 18, usd: null },
+  ],
+};
+
+/** RPC endpoint for an EVM rail name. */
+export function evmRpcFor(rail) {
+  return rail === 'base' ? config.baseRpcUrl : rail === 'robinhood' ? config.rhRpcUrl : null;
+}
+
 /**
  * The one canonical way to tell a user how to fund the SOLANA rail. Callers
  * pass the Solana address; the rail is named explicitly because the wallet
@@ -45,9 +75,11 @@ export function fundingLine(address) {
  * Solana: quoted in settlement mints, converted from plain USDC / TOKEN at
  *   payment time (lib/wrap.js).
  * Base:   quoted in native USDC — funded and spent as-is, no conversion.
- * Robinhood: quoted in a settlement asset with no conversion path on EVM
- *   (wrapping is Solana-only), so there is no plain balance a user can fund
- *   and have the shim pay from — hence no assets, and no funding line.
+ * Robinhood: the rail settles (real payments 2026-08-14), but it is quoted in
+ *   a settlement asset with no conversion path in this shim (wrapping is
+ *   Solana-only). To pay here, deposit USDG into the vault yourself at
+ *   https://x402.accrue.fund/start so the wallet holds the settlement asset —
+ *   there is no PLAIN balance the shim can auto-convert, hence no assets here.
  */
 export const RAIL_FUNDING = {
   solana: { label: 'Solana', assets: ['USDC', 'TOKEN'] },

package/lib/evm.js

@@ -1,7 +1,28 @@
 import crypto from 'node:crypto';
+import { createPublicClient, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { evmChainId } from './x402.js';
 
+const ERC20_ABI = [
+  { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ name: 'a', type: 'address' }], outputs: [{ type: 'uint256' }] },
+];
+
+const evmClients = new Map();
+function clientFor(rpcUrl) {
+  if (!evmClients.has(rpcUrl)) evmClients.set(rpcUrl, createPublicClient({ transport: http(rpcUrl) }));
+  return evmClients.get(rpcUrl);
+}
+
+/** ERC-20 balance (raw bigint) of `owner` for `token` on the chain at `rpcUrl`. */
+export async function evmTokenBalance({ rpcUrl, token, owner }) {
+  return clientFor(rpcUrl).readContract({ address: token, abi: ERC20_ABI, functionName: 'balanceOf', args: [owner] });
+}
+
+/** Native gas balance (wei bigint) of `owner` on the chain at `rpcUrl`. */
+export async function evmNativeBalance({ rpcUrl, owner }) {
+  return clientFor(rpcUrl).getBalance({ address: owner });
+}
+
 /**
  * EVM rails (Base eip155:8453; Robinhood Chain eip155:4663 behind OPENZOO_ENABLE_RH).
  *
@@ -15,9 +36,10 @@ import { evmChainId } from './x402.js';
  * We never scale by decimals, so the zoo's /prompt.txt "decimals = 6" bug
  * (wrong for the 18-decimal Robinhood mints) cannot bite this path.
  *
- * STATUS: code-present, live-UNTESTED — the zoo's 402s currently offer only
- * Solana rows, and whether its facilitator settles eip155 chains at all is
- * unverified upstream.
+ * STATUS: live. Real payments have settled on both EVM rails (2026-08-14):
+ * native USDC on Base (eip155:8453) and the RH settlement asset on Robinhood
+ * Chain (eip155:4663), both via EIP-3009 batched settlement through the
+ * facilitator. Steer to a rail with OPENZOO_RAIL.
  */
 export async function buildEvmPayment({ accept, evmPrivateKey }) {
   const chainId = evmChainId(accept.network);

package/lib/info.js

@@ -1,31 +1,75 @@
 import { Connection } from '@solana/web3.js';
 import { privateKeyToAccount } from 'viem/accounts';
-import { config, FUNDING_ASSETS, fundingLine } from './config.js';
+import { config, FUNDING_ASSETS, EVM_FUNDING_ASSETS, evmRpcFor, fundingLine } from './config.js';
 import { loadOrCreateWallet } from './wallet.js';
 import { tokenBalance } from './x402.js';
+import { evmTokenBalance, evmNativeBalance } from './evm.js';
 
 export function printAddress() {
   const { keypair, evmPrivateKey, created, path } = loadOrCreateWallet();
   if (created) console.log(`new burner wallet created at ${path} (chmod 600)`);
-  console.log(keypair.publicKey.toBase58());
-  console.log(`(evm, for the Base / Robinhood rails: ${privateKeyToAccount(evmPrivateKey).address})`);
+  console.log(`solana                    : ${keypair.publicKey.toBase58()}`);
+  console.log(`evm (Base · Robinhood)    : ${privateKeyToAccount(evmPrivateKey).address}`);
 }
 
+const CHAIN_LABEL = { base: 'Base', robinhood: 'Robinhood Chain' };
+
+function fmtUi(raw, decimals) {
+  return Number(raw) / 10 ** decimals;
+}
+
+/**
+ * Balance across every rail: Solana (USDC + TOKEN + SOL) and each EVM chain
+ * (stables, the RH memecoins, native gas). USD value is shown only where a
+ * price is known ($1 stables); everything else gets an honest `?`.
+ * A chain whose RPC does not answer prints as unreachable — never as zero.
+ */
 export async function printBalance() {
-  const { keypair } = loadOrCreateWallet();
+  const { keypair, evmPrivateKey } = loadOrCreateWallet();
+  const evmAddress = privateKeyToAccount(evmPrivateKey).address;
   const connection = new Connection(config.rpcUrl, 'confirmed');
+
+  // Solana ------------------------------------------------------------------
   const [balances, lamports] = await Promise.all([
     Promise.all(FUNDING_ASSETS.map((a) => tokenBalance(connection, keypair.publicKey, a.mint))),
     connection.getBalance(keypair.publicKey),
   ]);
   const usdcUi = balances[0].ui ?? 0;
-  console.log(`wallet : ${keypair.publicKey.toBase58()}`);
+  let knownUsd = usdcUi;
+  let anyFunds = balances.some((b) => b.raw);
+
+  console.log(`Solana — ${keypair.publicKey.toBase58()}`);
   FUNDING_ASSETS.forEach((a, i) => {
-    console.log(`${a.symbol.padEnd(7)}: ${balances[i].ui ?? 0}`);
+    const usd = a.symbol === 'USDC' ? ` ($${(balances[i].ui ?? 0).toFixed(2)})` : ' ($?, valued at the 402)';
+    console.log(`  ${a.symbol.padEnd(11)}: ${balances[i].ui ?? 0}${usd}`);
   });
-  console.log(`SOL    : ${lamports / 1e9}`);
-  console.log(`value  : ≈ $${usdcUi.toFixed(2)} (USDC leg; TOKEN valued at the 402)`);
-  if (!balances.some((b) => b.raw)) {
-    console.log(`fund   : ${fundingLine(keypair.publicKey.toBase58())}`);
+  console.log(`  ${'SOL'.padEnd(11)}: ${lamports / 1e9} (gas — optional, payments are sponsored)`);
+
+  // EVM chains --------------------------------------------------------------
+  for (const [rail, assets] of Object.entries(EVM_FUNDING_ASSETS)) {
+    const rpcUrl = evmRpcFor(rail);
+    console.log(`${CHAIN_LABEL[rail] ?? rail} — ${evmAddress}`);
+    try {
+      const [native, ...raws] = await Promise.all([
+        evmNativeBalance({ rpcUrl, owner: evmAddress }),
+        ...assets.map((a) => evmTokenBalance({ rpcUrl, token: a.address, owner: evmAddress })),
+      ]);
+      assets.forEach((a, i) => {
+        const ui = fmtUi(raws[i], a.decimals);
+        if (raws[i] > 0n) anyFunds = true;
+        if (a.usd != null) knownUsd += ui * a.usd;
+        const usd = a.usd != null ? ` ($${(ui * a.usd).toFixed(2)})` : ' ($?)';
+        console.log(`  ${a.symbol.padEnd(11)}: ${ui}${usd}`);
+      });
+      console.log(`  ${'ETH'.padEnd(11)}: ${fmtUi(native, 18)} (gas — optional, payments are sponsored)`);
+    } catch {
+      console.log('  (rpc unreachable — balances not checked, funds unaffected)');
+    }
+  }
+
+  console.log(`value : ≈ $${knownUsd.toFixed(2)} known (stable legs; TOKEN and the RH memecoins are priced at the 402, shown as $?)`);
+  if (!anyFunds) {
+    console.log(`fund  : ${fundingLine(keypair.publicKey.toBase58())}`);
+    console.log(`        or USDC on Base to ${evmAddress}`);
   }
 }

package/lib/mcp.js

@@ -104,7 +104,7 @@ export async function startMcp() {
       railsLiveNow: rails?.live ?? null,
       fundWith: hint || `${FUNDING_ASSETS.map((a) => a.symbol).join(' or ')} on Solana`,
       solanaMints: Object.fromEntries(FUNDING_ASSETS.map((a) => [a.symbol, a.mint])),
-      fundHint: 'send a few cents of a listed asset to the address for that rail — Solana assets to solanaAddress, Base assets to evmAddress. The shim converts to whatever the 402 quotes, at payment time.',
+      fundHint: 'send a few cents of a listed asset to the address for that rail — Solana assets to solanaAddress, Base assets to evmAddress. The shim converts to whatever the 402 quotes, at payment time. Force a rail with OPENZOO_RAIL=solana|base|robinhood.',
       balances,
       receipts: client.receipts.map((r) => ({ at: r.at, line: r.line })),
     });

package/lib/pay.js

@@ -6,7 +6,7 @@ import {
   parse402, pickAccept, railOf, buildPaymentOnline, tokenBalance,
   receiptLine, decodeSettleHeader,
 } from './x402.js';
-import { buildEvmPayment } from './evm.js';
+import { buildEvmPayment, evmTokenBalance } from './evm.js';
 import { privateKeyToAccount } from 'viem/accounts';
 import {
   resolvePool, poolState, depositForShares, buildWrapInstructions, sendWrap,
@@ -21,11 +21,13 @@ export class QuoteTooHighError extends Error {
 }
 
 export class UnderfundedError extends Error {
-  constructor(accept, usdcUi, address) {
+  constructor(accept, usdcUi, address, { line } = {}) {
     const usd = Number(accept?.extra?.billedUsd);
     const needs = Number.isFinite(usd) ? `this call needs ≈$${usd.toFixed(6)}` : 'this call needs more than the wallet holds';
     const holds = usdcUi != null ? ` — the wallet holds $${Number(usdcUi).toFixed(2)} USDC` : '';
-    super(`openzoo wallet underfunded: ${needs}${holds}. ${fundingLine(address).replace(/^s/, 'S')}.`);
+    super(line
+      ? `openzoo wallet underfunded: ${needs}. ${line}`
+      : `openzoo wallet underfunded: ${needs}${holds}. ${fundingLine(address).replace(/^s/, 'S')}.`);
     this.accept = accept;
     this.usdcUi = usdcUi;
     this.address = address;
@@ -72,7 +74,23 @@ export class PayClient {
       }
       return buildPaymentOnline(this.connection, this.keypair, accept);
     }
-    if (rail === 'base' || rail === 'evm' || (rail === 'robinhood' && this.allowRH)) {
+    // OPENZOO_RAIL=robinhood is explicit intent — it opens the RH gate the
+    // same way OPENZOO_ENABLE_RH=1 does.
+    if (rail === 'base' || rail === 'evm' || (rail === 'robinhood' && (this.allowRH || config.rail === 'robinhood'))) {
+      // 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;
+      const owner = this.evmAddress;
+      if (owner) {
+        const bal = await evmTokenBalance({ rpcUrl, token: accept.asset, owner }).catch(() => null);
+        if (bal !== null && bal < BigInt(accept.maxAmountRequired)) {
+          const line = rail === 'base'
+            ? `Send a few cents of USDC on Base to ${owner}.`
+            : `The wallet must hold the Robinhood Chain settlement asset — deposit USDG at https://x402.accrue.fund/start (wallet: ${owner}).`;
+          throw new UnderfundedError(accept, null, owner, { line });
+        }
+      }
       return buildEvmPayment({ accept, evmPrivateKey: this.evmPrivateKey });
     }
     throw new Error(`no payment builder for rail ${rail} (network ${accept.network})`);
@@ -141,7 +159,9 @@ export class PayClient {
     if (first.status !== 402) return { response: first, paid: false };
 
     const quote = parse402(await first.json());
-    const accept = pickAccept(quote, config.token, { allowRH: this.allowRH });
+    // config.rail (OPENZOO_RAIL) steers every front — proxy, demo, MCP — since
+    // they all pay through this one call site.
+    const accept = pickAccept(quote, config.token, { allowRH: this.allowRH, forceRail: config.rail });
     const billedUsd = Number(accept?.extra?.billedUsd ?? NaN);
     if (Number.isFinite(billedUsd) && billedUsd > config.maxUsdPerCall) {
       throw new QuoteTooHighError(billedUsd, quote);

package/lib/proxy.js

@@ -104,12 +104,32 @@ async function maybeCacheCorpus(req, bodyBuf, log) {
   };
 }
 
-export async function startProxy({ silent = false } = {}) {
+/**
+ * `requireToken` / `sessionMaxUsd` are TUNNEL MODE (see lib/tunnel.js): once the
+ * proxy is reachable from the internet, the api key stops being decorative and
+ * becomes the only thing between a stranger and your wallet. Both are off by
+ * default, so localhost behaviour is unchanged.
+ */
+export async function startProxy({ silent = false, requireToken = null, sessionMaxUsd = null } = {}) {
   const client = new PayClient();
   const log = silent ? () => {} : (...a) => console.log(...a);
+  let sessionSpent = 0;
 
   const server = http.createServer(async (req, res) => {
     const url = `${config.apiBase}${req.url}`;
+    // Auth first: refuse before reading a body, forwarding, quoting or paying.
+    if (requireToken) {
+      const got = (req.headers.authorization || '').replace(/^Bearer\s+/i, '').trim();
+      if (got !== requireToken) {
+        log(`tunnel: 401 ${req.method} ${req.url} from ${req.socket.remoteAddress}`);
+        jsonErr(res, 401, 'unauthorized: this openzoo tunnel requires the api key printed at startup');
+        return;
+      }
+      if (sessionMaxUsd != null && sessionSpent >= sessionMaxUsd) {
+        jsonErr(res, 402, `openzoo tunnel session cap reached ($${sessionMaxUsd}) — restart the tunnel or raise OPENZOO_TUNNEL_MAX_USD`);
+        return;
+      }
+    }
     let bodyBuf;
     try {
       bodyBuf = await readBody(req);
@@ -154,7 +174,13 @@ export async function startProxy({ silent = false } = {}) {
         result = await client.fetch(url, init);
       }
       const { response, paid, receipt } = result;
-      if (paid && receipt) log(receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`);
+      if (paid && receipt) {
+        if (receipt.ok && typeof receipt.billedUsd === 'number') sessionSpent += receipt.billedUsd;
+        const line = receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`;
+        // In tunnel mode the running total is the thing you actually want to
+        // watch, so it rides on every receipt.
+        log(requireToken ? `${line}  ·  session $${sessionSpent.toFixed(6)}` : line);
+      }
       await relay(res, response);
     } catch (err) {
       if (err instanceof QuoteTooHighError) {
@@ -218,5 +244,5 @@ export async function startProxy({ silent = false } = {}) {
     console.log(`  base_url = http://localhost:${config.port}/v1`);
     console.log('  api_key  = sk-openzoo   (any value works; the zoo takes payment, not keys)');
   }
-  return { server, client };
+  return { server, client, spent: () => sessionSpent };
 }

package/lib/tunnel.js

@@ -0,0 +1,156 @@
+/**
+ * `npx openzoo tunnel` — make the local paying proxy reachable from a CLOUD-run
+ * harness.
+ *
+ * WHY THIS EXISTS: IDEs that execute model calls from their own servers cannot
+ * dial your laptop. Pointing one at http://localhost:8402 returns, verbatim:
+ *   "Provider returned error: Access to private networks is forbidden"
+ * The payment path is fine — the harness just can't reach it. A tunnel gives
+ * that harness a public HTTPS URL while your keys stay on this machine.
+ *
+ * SELF-PROVISIONING: we do not ask you to install anything. If `cloudflared`
+ * isn't on PATH we fetch the single static binary for this platform into
+ * ~/.openzoo/bin and cache it. Quick tunnels need no Cloudflare account.
+ *
+ * SECURITY IS THE DESIGN. A public URL in front of a wallet is a public URL in
+ * front of your money, so tunnel mode is the ONE mode where the api key is real:
+ *   - a random bearer token is minted per session and REQUIRED (401 otherwise),
+ *     checked before anything is forwarded, quoted, or paid;
+ *   - the per-call cap (OPENZOO_MAX_USD_PER_CALL) still applies, and a session
+ *     ceiling (OPENZOO_TUNNEL_MAX_USD, default $1) stops paying when reached;
+ *   - every tunnel-served request is logged with its running spend.
+ */
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+
+const BIN_DIR = path.join(os.homedir(), '.openzoo', 'bin');
+
+/** cloudflared publishes one static binary per platform; pick ours. */
+function cloudflaredAsset() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin') return { name: 'cloudflared-darwin-amd64.tgz', tgz: true };
+  if (p === 'linux') {
+    const arch = a === 'arm64' ? 'arm64' : a === 'arm' ? 'arm' : 'amd64';
+    return { name: `cloudflared-linux-${arch}`, tgz: false };
+  }
+  if (p === 'win32') return { name: 'cloudflared-windows-amd64.exe', tgz: false };
+  return null;
+}
+
+function onPath(bin) {
+  const dirs = (process.env.PATH || '').split(path.delimiter);
+  for (const d of dirs) {
+    const f = path.join(d, bin);
+    try { fs.accessSync(f, fs.constants.X_OK); return f; } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+/**
+ * Return a usable cloudflared path, downloading it if needed. Order: PATH, our
+ * cache, then the official GitHub release. macOS ships a .tgz; the others are
+ * bare binaries.
+ */
+export async function ensureCloudflared(log = console.log) {
+  const found = onPath(process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  if (found) return found;
+
+  const cached = path.join(BIN_DIR, process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  try { fs.accessSync(cached, fs.constants.X_OK); return cached; } catch { /* fetch it */ }
+
+  const asset = cloudflaredAsset();
+  if (!asset) throw new Error(`no cloudflared build for ${process.platform}/${process.arch} — install it manually and re-run`);
+
+  fs.mkdirSync(BIN_DIR, { recursive: true, mode: 0o700 });
+  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset.name}`;
+  log(`fetching cloudflared for ${process.platform}/${process.arch} (one-time, ~35MB)...`);
+  const r = await fetch(url, { redirect: 'follow' });
+  if (!r.ok) throw new Error(`cloudflared download failed: HTTP ${r.status}`);
+
+  if (asset.tgz) {
+    const tgz = path.join(BIN_DIR, 'cloudflared.tgz');
+    await pipeline(Readable.fromWeb(r.body), createWriteStream(tgz));
+    await new Promise((resolve, reject) => {
+      const t = spawn('tar', ['xzf', tgz, '-C', BIN_DIR], { stdio: 'ignore' });
+      t.on('exit', (c) => (c === 0 ? resolve() : reject(new Error(`tar exited ${c}`))));
+      t.on('error', reject);
+    });
+    fs.rmSync(tgz, { force: true });
+  } else {
+    await pipeline(Readable.fromWeb(r.body), createWriteStream(cached));
+  }
+  fs.chmodSync(cached, 0o755);
+  log(`cloudflared cached at ${cached}`);
+  return cached;
+}
+
+/** Start a quick tunnel to localhost:<port>; resolve with its public URL. */
+export function startCloudflared(bin, port, log) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(bin, ['tunnel', '--url', `http://localhost:${port}`, '--no-autoupdate'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let settled = false;
+    const scan = (buf) => {
+      const m = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i.exec(buf.toString());
+      if (m && !settled) { settled = true; resolve({ url: m[0], proc }); }
+    };
+    proc.stdout.on('data', scan);
+    proc.stderr.on('data', scan); // cloudflared prints the URL on stderr
+    proc.on('error', reject);
+    proc.on('exit', (c) => { if (!settled) reject(new Error(`cloudflared exited ${c} before printing a URL`)); });
+    setTimeout(() => { if (!settled) reject(new Error('cloudflared did not produce a URL in 60s')); }, 60000);
+  });
+}
+
+export function mintToken() {
+  return process.env.OPENZOO_TUNNEL_TOKEN || `oz_${crypto.randomBytes(24).toString('base64url')}`;
+}
+
+export async function runTunnel() {
+  const { startProxy } = await import('./proxy.js');
+  const { config } = await import('./config.js');
+
+  const token = mintToken();
+  const sessionCap = Number(process.env.OPENZOO_TUNNEL_MAX_USD || 1);
+
+  // The proxy enforces the gate itself: nothing is forwarded, quoted or paid
+  // without the bearer token, and the session ceiling stops spend cold.
+  const { spent } = await startProxy({
+    silent: true,
+    requireToken: token,
+    sessionMaxUsd: sessionCap,
+  });
+
+  const bin = await ensureCloudflared();
+  const { url, proc } = await startCloudflared(bin, config.port, console.log);
+
+  console.log('');
+  console.log('  ┌─────────────────────────────────────────────────────────────');
+  console.log('  │  THIS URL SPENDS REAL MONEY FROM YOUR WALLET.');
+  console.log('  │  The token below is the only thing protecting it.');
+  console.log(`  │  Session ceiling: $${sessionCap.toFixed(2)} — then it stops paying.`);
+  console.log('  │  Ctrl-C when you are done; the URL dies with this process.');
+  console.log('  └─────────────────────────────────────────────────────────────');
+  console.log('');
+  console.log('point your cloud IDE at:');
+  console.log(`  base_url = ${url}/v1`);
+  console.log(`  api_key  = ${token}`);
+  console.log('');
+
+  const shutdown = () => {
+    try { proc.kill('SIGTERM'); } catch { /* already gone */ }
+    const total = typeof spent === 'function' ? spent() : 0;
+    console.log(`\ntunnel closed — session spend $${total.toFixed(6)}`);
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}

package/lib/x402.js

@@ -62,13 +62,34 @@ export function evmChainId(network) {
 }
 
 /**
- * Choose the accepts[] row to pay with. Rail order: Solana first (preferring
- * extra.symbol === preferredSymbol), then Base, then other EVM chains.
- * Robinhood Chain (eip155:4663) only when allowRH — the zoo ships it dark
- * (RH_RAILS=0) and facilitator settlement there is unverified.
+ * Choose the accepts[] row to pay with.
+ *
+ * `forceRail` (env OPENZOO_RAIL=solana|base|robinhood) pins the selection to
+ * one rail and errors clearly when the live 402 does not offer it — forcing is
+ * explicit intent, so it also bypasses the allowRH gate.
+ *
+ * Default order: Solana first (preferring extra.symbol === preferredSymbol),
+ * then Base, then other EVM chains. Robinhood Chain (eip155:4663) is last and
+ * only when allowRH: all three rails have settled real payments (2026-08-14),
+ * but RH stays opt-in for DEFAULT selection because its settlement asset has
+ * no auto-conversion path here.
  */
-export function pickAccept(body, preferredSymbol, { allowRH = false } = {}) {
+export function pickAccept(body, preferredSymbol, { allowRH = false, forceRail = null } = {}) {
   const rows = parse402(body).accepts.filter((a) => a?.scheme === 'exact');
+  if (forceRail) {
+    const want = String(forceRail).toLowerCase();
+    if (!['solana', 'base', 'robinhood', 'evm'].includes(want)) {
+      throw new Error(`OPENZOO_RAIL=${forceRail} is not a rail — use solana, base or robinhood`);
+    }
+    const match = rows.filter((a) => railOf(a) === want);
+    if (!match.length) {
+      const offered = [...new Set(rows.map(railOf).filter(Boolean))];
+      throw new Error(
+        `OPENZOO_RAIL=${want} but the live 402 offers no ${want} rail (offered: ${offered.join(', ') || 'none'})`,
+      );
+    }
+    return match.find((a) => a?.extra?.symbol === preferredSymbol) || match[0];
+  }
   const sol = rows.filter((a) => railOf(a) === 'solana');
   if (sol.length) return sol.find((a) => a?.extra?.symbol === preferredSymbol) || sol[0];
   const base = rows.filter((a) => railOf(a) === 'base');
@@ -78,7 +99,7 @@ export function pickAccept(body, preferredSymbol, { allowRH = false } = {}) {
   const rh = rows.filter((a) => railOf(a) === 'robinhood');
   if (allowRH && rh.length) return rh[0];
   throw new Error(rh.length
-    ? 'only Robinhood Chain rails offered — set OPENZOO_ENABLE_RH=1 to use them (experimental, settlement unverified)'
+    ? 'only Robinhood Chain rails offered — set OPENZOO_ENABLE_RH=1 or OPENZOO_RAIL=robinhood to use them (the rail settles; you must hold its settlement asset, see https://x402.accrue.fund/start)'
     : 'no payable rail in 402 accepts[]');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",