openzoo 0.5.0 → 0.6.0

package/README.md

@@ -168,8 +168,9 @@ Pin the key with `OPENZOO_TUNNEL_TOKEN` if your IDE stores it. Keys never leave
 
   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
 
@@ -182,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
 
@@ -200,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

@@ -12,21 +12,29 @@ usage:
                          (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() {

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/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.5.0",
+  "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",