openzoo 0.1.0 → 0.2.0

package/README.md

@@ -40,7 +40,25 @@ curl http://localhost:8402/v1/chat/completions -H 'Content-Type: application/jso
   -d '{"model":"nvidia/nemotron-3.5-lightning","messages":[{"role":"user","content":"hi"}]}'
 ```
 
-Model ids come from `GET http://localhost:8402/v1/models` (free, no payment).
+**OpenAI SDK (Python):**
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:8402/v1", api_key="sk-openzoo")
+r = client.chat.completions.create(model="nvidia/nemotron-3.5-lightning",
+                                   messages=[{"role": "user", "content": "hi"}])
+```
+
+**OpenAI SDK (JS/TS):**
+```js
+import OpenAI from "openai";
+const client = new OpenAI({ baseURL: "http://localhost:8402/v1", apiKey: "sk-openzoo" });
+const r = await client.chat.completions.create({
+  model: "nvidia/nemotron-3.5-lightning",
+  messages: [{ role: "user", content: "hi" }],
+});
+```
+
+Model ids come from `GET http://localhost:8402/v1/models` (free, no payment). Requires Node ≥ 18 (for `npx openzoo` itself; your harness can be anything).
 
 ## Use as MCP
 
@@ -50,12 +68,16 @@ The same package is an MCP server sharing the same wallet and payment core:
 claude mcp add openzoo -- npx -y openzoo mcp
 ```
 
-Other MCP hosts:
+**Claude Desktop** — add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`), then restart the app:
 
 ```json
 { "mcpServers": { "openzoo": { "command": "npx", "args": ["-y", "openzoo", "mcp"] } } }
 ```
 
+**Cursor** — Settings → MCP → *Add new global MCP server*, or drop the same JSON into `~/.cursor/mcp.json` (per-project: `.cursor/mcp.json`).
+
+**Windsurf / Cline / any MCP host** — same shape: command `npx`, args `["-y", "openzoo", "mcp"]`, stdio transport.
+
 Tools:
 - **`zoo_ask`** — `{prompt, corpus?, model?, max_tokens?}`. The flagship: hand it a *huge* `corpus` (hundreds of thousands to ~1M tokens — a body the model itself would refuse) and a question; the zoo's leCore memory spills the corpus so the model reads only a few thousand tokens. Returns the answer plus the receipt (`billedUsd`, `savesVsDirect`, tokens actually read). An MCP-capable agent can delegate a giant-context question without touching its own model config.
 - **`zoo_models`** — list the zoo's models and pricing (free).
@@ -70,18 +92,18 @@ npx openzoo demo
 Builds a ~965k-token document with one planted fact, shows that buying direct refuses it (*"The input token count exceeds the maximum number of tokens allowed."* — recorded, see [benches.openzoo.fun](https://benches.openzoo.fun)), then fetches the live x402 quote for the same body — the quote is free:
 
 ```
-quote: $0.009747 yUSDCx · pricing=counterfactual · direct would be $0.097474 · savesVsDirect=10.0×
+quote: $0.009747 · pricing=counterfactual · direct would be $0.097474 · savesVsDirect=10.0×
 ```
 
-If the wallet is funded it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund.
+If the wallet is funded with USDC it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund. Long waits (the multi-MB upload, pricing, payment, the answer) show a live progress line with stage + elapsed seconds.
 
 ## 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.
-- **Fund it with yUSDCx** (mint `6ZjjxcoicqM4nniddkuPVwew4PDwY3swbfHsGbCuLuTv`), the $1-stable rail: wrap USDC at [x402.accrue.fund/start](https://x402.accrue.fund/start) and send to the address `npx openzoo address` prints. A few cents goes a long way.
-- **You don't need SOL.** The gateway is the transaction feePayer; you only sign the token transfer.
+- **Fund it with plain USDC.** Send a few cents of USDC to the address `npx openzoo address` prints. That's the whole funding story — the shim converts whatever 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.
 - **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 / print the address.
+- `npx openzoo balance` / `npx openzoo address` — check funds (USDC + SOL + USD value) / print the address.
 
 ## Honest pricing note
 
@@ -95,7 +117,7 @@ The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect`
 
 | rail | network | status |
 |---|---|---|
-| **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Tested end-to-end against the production 402. |
+| **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. |
 | Base | `eip155:8453` | implemented (standard x402 EIP-3009 `transferWithAuthorization`), **live-untested** — the zoo's 402s currently offer only Solana rows. |
 | Robinhood Chain | `eip155:4663` | experimental, behind `OPENZOO_ENABLE_RH=1` — the zoo ships this rail dark and facilitator settlement there is unverified. |
 
@@ -108,7 +130,7 @@ The rail is chosen from the 402's `accepts[]` itself (Solana first). Amounts are
 | `OPENZOO_PORT` | `8402` | proxy port |
 | `OPENZOO_API_BASE` | `https://x402-tokens.fly.dev` | the zoo's door |
 | `OPENZOO_RPC` | mainnet-beta public RPC | Solana RPC |
-| `OPENZOO_TOKEN` | `yUSDCx` | which 402 row to pay |
+| `OPENZOO_TOKEN` | (internal) | preferred 402 rail — leave unset |
 | `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 |

package/bin/openzoo.js

@@ -7,7 +7,7 @@ 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 demo       ~1M-token needle demo: direct refuses, the zoo answers
-  npx openzoo balance    wallet balances (yUSDCx / wTOKENx)
+  npx openzoo balance    wallet balance (USDC + SOL, with USD value)
   npx openzoo address    print the funding address
   npx openzoo help       this text
 
@@ -17,7 +17,7 @@ point any OpenAI-compatible harness at:
 
 env:
   OPENZOO_PORT (8402)  OPENZOO_API_BASE (https://x402-tokens.fly.dev)
-  OPENZOO_RPC (mainnet-beta)  OPENZOO_TOKEN (yUSDCx)  OPENZOO_WALLET (~/.openzoo/wallet.json)
+  OPENZOO_RPC (mainnet-beta)  OPENZOO_TOKEN (402 rail preference)  OPENZOO_WALLET (~/.openzoo/wallet.json)
   OPENZOO_MAX_USD_PER_CALL (0.5)  OPENZOO_DEMO_MAX_USD (0.01)
   OPENZOO_ENABLE_RH (0 — Robinhood Chain rail, experimental)`;
 

package/lib/config.js

@@ -5,7 +5,7 @@ export const config = {
   port: Number(process.env.OPENZOO_PORT || 8402),
   apiBase: (process.env.OPENZOO_API_BASE || 'https://x402-tokens.fly.dev').replace(/\/+$/, ''),
   rpcUrl: process.env.OPENZOO_RPC || 'https://api.mainnet-beta.solana.com',
-  // Which accepts[] row to pay with, by extra.symbol. yUSDCx is the $1-stable rail.
+  // Which accepts[] row to pay with, by extra.symbol (internal rail selector).
   token: process.env.OPENZOO_TOKEN || 'yUSDCx',
   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).

package/lib/demo.js

@@ -1,6 +1,8 @@
 import { config } from './config.js';
-import { PayClient } from './pay.js';
+import { PayClient, UnderfundedError } from './pay.js';
 import { parse402, pickAccept, tokenBalance } from './x402.js';
+import { startSpinner, postWithUploadSignal } from './spinner.js';
+import { resolvePool, poolState, depositForShares } from './wrap.js';
 
 const DEMO_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
 const NEEDLE = 'The zebra vault code is 7-ALPHA-9243.';
@@ -28,13 +30,32 @@ function bigBody(targetTokens) {
 }
 
 async function quoteFor(bodyObj) {
-  const r = await fetch(`${config.apiBase}/v1/chat/completions`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify(bodyObj),
-  });
-  if (r.status !== 402) throw new Error(`expected 402 quote, got HTTP ${r.status}: ${(await r.text()).slice(0, 300)}`);
-  return parse402(await r.json());
+  const body = JSON.stringify(bodyObj);
+  const mb = (body.length / 1048576).toFixed(1);
+  const approxTokens = Math.round(body.length / 4 / 1000);
+  const spin = startSpinner(`uploading ${mb}MB body`);
+  try {
+    const r = await postWithUploadSignal(`${config.apiBase}/v1/chat/completions`, body, {
+      onUploaded: () => spin.update(`zoo pricing ~${approxTokens}k tokens`),
+    });
+    if (r.status !== 402) throw new Error(`expected 402 quote, got HTTP ${r.status}: ${(await r.text()).slice(0, 300)}`);
+    return parse402(await r.json());
+  } finally {
+    spin.stop();
+  }
+}
+
+/** Can the wallet cover this quote (directly or by converting its USDC)? */
+async function coverage(connection, owner, accept) {
+  const need = BigInt(accept.maxAmountRequired);
+  const have = await tokenBalance(connection, owner, accept.asset);
+  if (have.raw >= need) return { covered: true, usdcUi: null };
+  const pool = await resolvePool(connection, accept.asset).catch(() => null);
+  if (!pool) return { covered: false, usdcUi: 0 };
+  const { reserves, supply } = await poolState(connection, pool);
+  const deposit = depositForShares(need - have.raw, reserves, supply);
+  const underlying = await tokenBalance(connection, owner, pool.underlying.toBase58());
+  return { covered: underlying.raw >= deposit, usdcUi: underlying.ui ?? 0 };
 }
 
 export async function runDemo() {
@@ -61,7 +82,7 @@ export async function runDemo() {
   const quote = await quoteFor(bodyObj);
   const accept = pickAccept(quote, config.token);
   const x = accept.extra || {};
-  console.log(`   quote: $${Number(x.billedUsd).toFixed(6)} ${x.symbol} · pricing=${x.pricing}`
+  console.log(`   quote: $${Number(x.billedUsd).toFixed(6)} · pricing=${x.pricing}`
     + (x.directUsd != null ? ` · direct would be $${Number(x.directUsd).toFixed(6)} · savesVsDirect=${Number(x.savesVsDirect).toFixed(1)}×` : ''));
   console.log('');
 
@@ -78,20 +99,35 @@ export async function runDemo() {
     payAccept = pickAccept(q2, config.token);
   }
 
-  const need = BigInt(payAccept.maxAmountRequired);
-  const bal = await tokenBalance(connection, keypair.publicKey, payAccept.asset);
-  if (bal.raw < need) {
+  const cov = await coverage(connection, keypair.publicKey, payAccept);
+  if (!cov.covered) {
     console.log('3) wallet not funded yet, so stopping before payment.');
-    console.log(`   need : ${need} raw units of ${payAccept.extra?.symbol} (mint ${payAccept.asset}) ≈ $${Number(payAccept.extra?.billedUsd).toFixed(6)}`);
-    console.log(`   have : ${bal.raw}`);
-    console.log(`   fund : ${pub}`);
-    console.log('   get yUSDCx by wrapping USDC: https://x402.accrue.fund/start — then re-run `npx openzoo demo`.');
+    console.log(`   quote : ≈ $${Number(payAccept.extra?.billedUsd).toFixed(6)}`);
+    console.log(`   wallet: $${(cov.usdcUi ?? 0).toFixed(2)} USDC`);
+    console.log(`   fund  : send a few cents of USDC to ${pub}`);
+    console.log('   then re-run `npx openzoo demo`.');
     return;
   }
 
   console.log('3) paying and asking...');
+  const paidMb = (JSON.stringify(payBody).length / 1048576).toFixed(1);
+  const spin = startSpinner(`re-sending ${paidMb}MB body for the paid call`);
   const t0 = Date.now();
-  const { data, receipt } = await client.chat(payBody);
+  let data; let receipt;
+  try {
+    ({ data, receipt } = await client.chat(payBody, {
+      onStage: (stage) => {
+        if (stage === 'quoted') spin.update('building the payment');
+        if (stage === 'funding') spin.update('preparing funds (one-time)');
+        if (stage === 'paying') spin.update('paying + waiting for the answer');
+      },
+    }));
+  } catch (err) {
+    spin.stop();
+    if (err instanceof UnderfundedError) { console.log(`   ${err.message}`); return; }
+    throw err;
+  }
+  spin.stop();
   const secs = ((Date.now() - t0) / 1000).toFixed(1);
   const answer = data?.choices?.[0]?.message?.content ?? '';
   const usage = data?.usage || {};

package/lib/info.js

@@ -4,8 +4,7 @@ import { config } from './config.js';
 import { loadOrCreateWallet } from './wallet.js';
 import { tokenBalance } from './x402.js';
 
-const YUSDCX = '6ZjjxcoicqM4nniddkuPVwew4PDwY3swbfHsGbCuLuTv';
-const WTOKENX = 'Bo7xBF7SY8EyUBPUxRP66SFafxoPf2n5uqiLjbxEebx9';
+const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 
 export function printAddress() {
   const { keypair, evmPrivateKey, created, path } = loadOrCreateWallet();
@@ -17,14 +16,16 @@ export function printAddress() {
 export async function printBalance() {
   const { keypair } = loadOrCreateWallet();
   const connection = new Connection(config.rpcUrl, 'confirmed');
-  const [y, w] = await Promise.all([
-    tokenBalance(connection, keypair.publicKey, YUSDCX),
-    tokenBalance(connection, keypair.publicKey, WTOKENX),
+  const [usdc, lamports] = await Promise.all([
+    tokenBalance(connection, keypair.publicKey, USDC),
+    connection.getBalance(keypair.publicKey),
   ]);
+  const usdcUi = usdc.ui ?? 0;
   console.log(`wallet : ${keypair.publicKey.toBase58()}`);
-  console.log(`yUSDCx : ${y.ui ?? 0}   (mint ${YUSDCX})`);
-  console.log(`wTOKENx: ${w.ui ?? 0}   (mint ${WTOKENX})`);
-  if (!y.raw && !w.raw) {
-    console.log('unfunded — wrap USDC into yUSDCx at https://x402.accrue.fund/start and send it here.');
+  console.log(`USDC   : ${usdcUi}`);
+  console.log(`SOL    : ${lamports / 1e9}`);
+  console.log(`value  : ≈ $${usdcUi.toFixed(2)}`);
+  if (!usdc.raw) {
+    console.log(`fund   : send a few cents of USDC to ${keypair.publicKey.toBase58()}`);
   }
 }

package/lib/mcp.js

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -5,8 +6,8 @@ import { config } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 
-const YUSDCX = '6ZjjxcoicqM4nniddkuPVwew4PDwY3swbfHsGbCuLuTv';
-const WTOKENX = 'Bo7xBF7SY8EyUBPUxRP66SFafxoPf2n5uqiLjbxEebx9';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 const DEFAULT_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
 
 function text(obj) {
@@ -16,7 +17,7 @@ function text(obj) {
 /** `npx openzoo mcp` — stdio MCP server sharing the proxy's wallet + payment core. */
 export async function startMcp() {
   const client = new PayClient();
-  const server = new McpServer({ name: 'openzoo', version: '0.1.0' });
+  const server = new McpServer({ name: 'openzoo', version: pkg.version });
 
   server.registerTool('zoo_ask', {
     description:
@@ -72,14 +73,14 @@ export async function startMcp() {
     description: 'The local burner wallet: funding address, balances, and this session\'s payment receipts.',
     inputSchema: {},
   }, async () => {
-    const [y, w] = await Promise.all([
-      tokenBalance(client.connection, client.keypair.publicKey, YUSDCX),
-      tokenBalance(client.connection, client.keypair.publicKey, WTOKENX),
+    const [usdc, lamports] = await Promise.all([
+      tokenBalance(client.connection, client.keypair.publicKey, USDC),
+      client.connection.getBalance(client.keypair.publicKey),
     ]);
     return text({
       solanaAddress: client.address,
-      fundWith: `yUSDCx (mint ${YUSDCX}) — wrap USDC at https://x402.accrue.fund/start`,
-      balances: { yUSDCx: y.ui ?? 0, wTOKENx: w.ui ?? 0 },
+      fundWith: 'USDC — send a few cents of USDC to this address',
+      balances: { USDC: usdc.ui ?? 0, SOL: lamports / 1e9, usdValue: usdc.ui ?? 0 },
       receipts: client.receipts.map((r) => ({ at: r.at, line: r.line })),
     });
   });

package/lib/pay.js

@@ -1,4 +1,5 @@
-import { Connection } from '@solana/web3.js';
+import { Connection, PublicKey } from '@solana/web3.js';
+import { getAssociatedTokenAddressSync } from '@solana/spl-token';
 import { config } from './config.js';
 import { loadOrCreateWallet } from './wallet.js';
 import {
@@ -6,6 +7,9 @@ import {
   receiptLine, decodeSettleHeader,
 } from './x402.js';
 import { buildEvmPayment } from './evm.js';
+import {
+  resolvePool, poolState, depositForShares, buildWrapInstructions, sendWrap,
+} from './wrap.js';
 
 export class QuoteTooHighError extends Error {
   constructor(billedUsd, quote) {
@@ -16,10 +20,13 @@ export class QuoteTooHighError extends Error {
 }
 
 export class UnderfundedError extends Error {
-  constructor(accept, have, address) {
-    super(`openzoo wallet underfunded: need ${accept.maxAmountRequired} raw ${accept.extra?.symbol || ''} (mint ${accept.asset}), have ${have}. Fund ${address}`);
+  constructor(accept, usdcUi, address) {
+    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}. Send a few cents of USDC to ${address}.`);
     this.accept = accept;
-    this.have = have;
+    this.usdcUi = usdcUi;
     this.address = address;
   }
 }
@@ -43,12 +50,18 @@ export class PayClient {
 
   get address() { return this.keypair.publicKey.toBase58(); }
 
-  async buildPaymentFor(accept) {
+  async buildPaymentFor(accept, onStage) {
     const rail = railOf(accept);
     if (rail === 'solana') {
+      const need = BigInt(accept.maxAmountRequired);
       const bal = await tokenBalance(this.connection, this.keypair.publicKey, accept.asset);
-      if (bal.raw < BigInt(accept.maxAmountRequired)) {
-        throw new UnderfundedError(accept, bal.raw, this.address);
+      if (bal.raw < need) {
+        const topUp = await this.topUpQuotedAsset(accept, need, onStage);
+        if (topUp.preInstructions) {
+          return buildPaymentOnline(this.connection, this.keypair, accept, {
+            preInstructions: topUp.preInstructions,
+          });
+        }
       }
       return buildPaymentOnline(this.connection, this.keypair, accept);
     }
@@ -58,12 +71,65 @@ export class PayClient {
     throw new Error(`no payment builder for rail ${rail} (network ${accept.network})`);
   }
 
+  /**
+   * Internal: make sure the wallet holds enough of the exact asset the 402
+   * quotes, by converting the user's plain USDC (or whatever underlying the
+   * pool takes) at payment time. Users never see or hold the quoted asset.
+   *
+   * Returns {} when the balance now covers the quote, or
+   * { preInstructions } when the wallet cannot pay network fees itself — the
+   * conversion then rides inside the gateway-sponsored payment transaction
+   * (the 402's feePayer covers fees and any account rent).
+   * Throws UnderfundedError when the underlying balance cannot cover it.
+   */
+  async topUpQuotedAsset(accept, need, onStage) {
+    const owner = this.keypair.publicKey;
+    const pool = await resolvePool(this.connection, accept.asset).catch(() => null);
+    if (!pool) throw new UnderfundedError(accept, null, this.address);
+
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const bal = await tokenBalance(this.connection, owner, accept.asset);
+      const short = need - bal.raw;
+      if (short <= 0n) return {};
+
+      const { reserves, supply } = await poolState(this.connection, pool);
+      const deposit = depositForShares(short, reserves, supply);
+      const underlyingBal = await tokenBalance(this.connection, owner, pool.underlying.toBase58());
+      if (underlyingBal.raw < deposit) {
+        throw new UnderfundedError(accept, underlyingBal.ui, this.address);
+      }
+
+      onStage?.('funding');
+      const wrappedAta = getAssociatedTokenAddressSync(pool.wrapped, owner, false, pool.wrappedProgram);
+      const [lamports, ataInfo] = await Promise.all([
+        this.connection.getBalance(owner),
+        this.connection.getAccountInfo(wrappedAta),
+      ]);
+      const lamportsNeeded = 10000 + (ataInfo ? 0 : 2400000); // tx fee + possible ATA rent
+      if (lamports < lamportsNeeded && accept.extra?.feePayer) {
+        // No SOL for a standalone conversion — bundle it into the payment tx.
+        const rentPayer = new PublicKey(accept.extra.feePayer);
+        return {
+          preInstructions: buildWrapInstructions({ pool, owner, depositRaw: deposit, rentPayer }),
+        };
+      }
+      const sig = await sendWrap(this.connection, this.keypair, pool, deposit);
+      this.lastTopUpSig = sig; // internal breadcrumb, never printed to users
+      if (process.env.OPENZOO_DEBUG) console.error(`[openzoo debug] top-up tx ${sig}`);
+    }
+
+    const finalBal = await tokenBalance(this.connection, owner, accept.asset);
+    if (finalBal.raw < need) throw new UnderfundedError(accept, null, this.address);
+    return {};
+  }
+
   /**
    * fetch that transparently pays a 402 once.
    * Returns { response, paid, accept?, settle?, receipt? }.
    * Throws QuoteTooHighError / UnderfundedError before any value moves.
    */
-  async fetch(url, init = {}) {
+  async fetch(url, init = {}, { onStage } = {}) {
+    onStage?.('request');
     const first = await fetch(url, init);
     if (first.status !== 402) return { response: first, paid: false };
 
@@ -74,7 +140,9 @@ export class PayClient {
       throw new QuoteTooHighError(billedUsd, quote);
     }
 
-    const payment = await this.buildPaymentFor(accept);
+    onStage?.('quoted');
+    const payment = await this.buildPaymentFor(accept, onStage);
+    onStage?.('paying');
     const response = await fetch(url, {
       ...init,
       headers: { ...(init.headers || {}), 'X-PAYMENT': payment.header },
@@ -101,12 +169,12 @@ export class PayClient {
   }
 
   /** POST a chat completion, paying as needed. Returns { data, receipt }. */
-  async chat(bodyObj) {
+  async chat(bodyObj, { onStage } = {}) {
     const { response, receipt } = await this.fetch(`${config.apiBase}/v1/chat/completions`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(bodyObj),
-    });
+    }, { onStage });
     if (!response.ok) {
       const text = (await response.text()).slice(0, 500);
       throw new Error(`zoo returned HTTP ${response.status}: ${text}`);

package/lib/proxy.js

@@ -93,12 +93,11 @@ export async function startProxy({ silent = false } = {}) {
     if (client.walletCreated) console.log(`new burner wallet created at ${client.walletPath} (chmod 600)`);
     console.log(`wallet (fund me): ${client.address}`);
     try {
-      // yUSDCx — the $1-stable rail this proxy pays with by default.
-      const yusdcx = '6ZjjxcoicqM4nniddkuPVwew4PDwY3swbfHsGbCuLuTv';
-      const bal = await tokenBalance(client.connection, client.keypair.publicKey, yusdcx);
-      console.log(`balance: ${bal.ui ?? 0} yUSDCx (mint ${yusdcx})`);
+      const usdc = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+      const bal = await tokenBalance(client.connection, client.keypair.publicKey, usdc);
+      console.log(`balance: ${bal.ui ?? 0} USDC (≈ $${(bal.ui ?? 0).toFixed(2)})`);
       if (!bal.raw) {
-        console.log('fund it with yUSDCx (wrap USDC at https://x402.accrue.fund/start) — a few cents goes a long way.');
+        console.log('fund it: send a few cents of USDC to the address above — a few cents goes a long way.');
       }
     } catch { /* RPC hiccup: balance is advisory */ }
     console.log('');

package/lib/spinner.js

@@ -0,0 +1,85 @@
+/**
+ * Tiny TTY-aware progress line for long waits (big-body upload, zoo pricing,
+ * payment settle). No deps: setInterval + \r rewrite on a TTY, plain periodic
+ * status lines when piped.
+ *
+ *   const spin = startSpinner('uploading 3.8MB body');
+ *   spin.update('zoo pricing 965k tokens');
+ *   spin.stop();            // clears the line; caller prints the result
+ */
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+export function startSpinner(initialLabel, { stream = process.stdout } = {}) {
+  const t0 = Date.now();
+  let label = initialLabel;
+  let frame = 0;
+  let stopped = false;
+  const secs = () => Math.round((Date.now() - t0) / 1000);
+
+  let timer;
+  if (stream.isTTY) {
+    timer = setInterval(() => {
+      frame = (frame + 1) % FRAMES.length;
+      stream.write(`\r\x1b[2K${FRAMES[frame]} ${label}… ${secs()}s`);
+    }, 100);
+  } else {
+    let lastPrinted = -5;
+    timer = setInterval(() => {
+      if (secs() - lastPrinted >= 5) {
+        lastPrinted = secs();
+        stream.write(`${label}… ${lastPrinted}s\n`);
+      }
+    }, 1000);
+  }
+  timer.unref?.();
+
+  return {
+    update(newLabel) { label = newLabel; },
+    elapsed: secs,
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (stream.isTTY) stream.write('\r\x1b[2K');
+    },
+  };
+}
+
+/**
+ * POST a large JSON body with an upload-completion callback, so callers can
+ * flip a spinner label from "uploading" to "server working". Tries a streamed
+ * (chunked) upload — the pull() callback tells us when the socket drained the
+ * body — and falls back to a plain buffered POST if the runtime or server
+ * doesn't take streamed request bodies.
+ */
+export async function postWithUploadSignal(url, bodyString, { headers = {}, onUploaded } = {}) {
+  const buf = Buffer.from(bodyString);
+  if (typeof ReadableStream === 'function' && buf.length > 262144) {
+    try {
+      let off = 0;
+      const stream = new ReadableStream({
+        pull(c) {
+          if (off >= buf.length) { c.close(); onUploaded?.(); return; }
+          const end = Math.min(off + 65536, buf.length);
+          c.enqueue(buf.subarray(off, end));
+          off = end;
+        },
+      });
+      const r = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: stream,
+        duplex: 'half',
+      });
+      // 411/413 = server refused the chunked upload; retry buffered below.
+      if (r.status !== 411 && r.status !== 413) return r;
+    } catch { /* runtime without duplex streams — fall through */ }
+  }
+  const r = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: buf,
+  });
+  onUploaded?.();
+  return r;
+}

package/lib/wrap.js

@@ -0,0 +1,208 @@
+/**
+ * Internal funding plumbing for Solana 402 rails.
+ *
+ * The zoo's Solana quotes settle in a NAV-wrapped Token-2022 mint issued by
+ * the wrap-nav program (FrSER…). Users only ever hold and send plain USDC —
+ * this module converts the exact amount needed, at payment time, inside the
+ * shim. Nothing here is user-facing; never surface wrapped tickers or mints
+ * in messages that reach the user.
+ *
+ * Verified against the deployed program's own e2e (solana-token-wrap/e2e/e2e.mjs)
+ * and live mainnet wrap transactions:
+ *   wrap ix: data = [1][amount u64 LE][authority bump]
+ *            keys = [escrow(w), wrappedMint(w), userWrappedAta(w),
+ *                    authorityPDA, wrappedTokenProgram]
+ *   shares minted = floor(amount * supply / reserves), reserves read at ix
+ *   execution — so the wrap ix is placed BEFORE the deposit TransferChecked.
+ *   First deposit is 1:1 minus MINIMUM_LIQUIDITY (1000) locked forever.
+ *   authority = PDA(['mint_authority', wrappedMint]); escrow = ATA(underlying,
+ *   authority); registry = PDA(['backpointer', wrappedMint]) when present.
+ */
+import { PublicKey, Transaction, TransactionInstruction, sendAndConfirmTransaction } from '@solana/web3.js';
+import {
+  TOKEN_PROGRAM_ID,
+  TOKEN_2022_PROGRAM_ID,
+  createAssociatedTokenAccountIdempotentInstruction,
+  createTransferCheckedInstruction,
+  getAssociatedTokenAddressSync,
+  unpackAccount,
+  unpackMint,
+} from '@solana/spl-token';
+
+export const WRAP_PROGRAM_ID = new PublicKey('FrSERTNCPvTtaDS9AvQp9u1nYGzXDb3kC9MdL8Xxn2NE');
+const AUTHORITY_SEED = Buffer.from('mint_authority');
+const BACKPOINTER_SEED = Buffer.from('backpointer');
+export const MINIMUM_LIQUIDITY = 1000n;
+
+// Machine-readable per-asset acquire directory published by the facilitator.
+// Consulted first so newly listed twins work with zero code changes; on-chain
+// derivation below is the fallback when the endpoint is unreachable.
+const SUPPORTED_URL = process.env.OPENZOO_SUPPORTED_URL || 'https://x402.accrue.fund/supported';
+let directoryCache = { at: 0, kinds: null };
+
+async function acquireDirectory() {
+  if (directoryCache.kinds && Date.now() - directoryCache.at < 300000) return directoryCache.kinds;
+  try {
+    const r = await fetch(SUPPORTED_URL, { signal: AbortSignal.timeout(8000) });
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    const body = await r.json();
+    if (Array.isArray(body?.kinds)) directoryCache = { at: Date.now(), kinds: body.kinds };
+  } catch { /* endpoint down — fall back to chain derivation */ }
+  return directoryCache.kinds;
+}
+
+/** /supported entry for a quoted Solana mint, or null. */
+async function directoryEntryFor(wrappedMintStr) {
+  const kinds = await acquireDirectory();
+  if (!kinds) return null;
+  const row = kinds.find((k) => k?.network?.startsWith?.('solana:') && k?.extra?.asset === wrappedMintStr);
+  const acq = row?.extra?.acquire;
+  return acq?.method === 'spl-token-wrap' && acq.underlying?.address && acq.escrow ? acq : null;
+}
+
+function u64le(n) { const b = Buffer.alloc(8); b.writeBigUInt64LE(BigInt(n)); return b; }
+
+/**
+ * Resolve the pool behind a quoted mint. Returns null when the mint is not a
+ * wrap-nav twin (then there is nothing this module can do for it).
+ * Generic over whatever mint the 402 quotes — nothing hardcoded per twin.
+ */
+export async function resolvePool(connection, wrappedMintStr) {
+  const wrapped = new PublicKey(wrappedMintStr);
+  const info = await connection.getAccountInfo(wrapped);
+  if (!info) return null;
+  const wrappedProgram = info.owner;
+  let mint;
+  try { mint = unpackMint(wrapped, info, wrappedProgram); } catch { return null; }
+
+  // Preferred source: the facilitator's own /supported directory.
+  const acq = await directoryEntryFor(wrappedMintStr);
+  if (acq) {
+    const programId = new PublicKey(acq.program || WRAP_PROGRAM_ID);
+    const authority = new PublicKey(acq.mintAuthority);
+    let bump = acq.authorityBump;
+    if (bump == null) {
+      const [derived, derivedBump] = PublicKey.findProgramAddressSync(
+        [AUTHORITY_SEED, wrapped.toBuffer()], programId,
+      );
+      if (derived.equals(authority)) bump = derivedBump;
+    }
+    if (bump != null && mint.mintAuthority?.equals(authority)) {
+      return {
+        wrapped,
+        wrappedProgram,
+        programId,
+        authority,
+        bump,
+        escrow: new PublicKey(acq.escrow),
+        underlying: new PublicKey(acq.underlying.address),
+        underlyingProgram: new PublicKey(acq.underlying.tokenProgram || TOKEN_PROGRAM_ID),
+        underlyingDecimals: acq.underlying.decimals ?? 6,
+      };
+    }
+  }
+
+  // Fallback: derive everything from chain state.
+  const [authority, bump] = PublicKey.findProgramAddressSync(
+    [AUTHORITY_SEED, wrapped.toBuffer()], WRAP_PROGRAM_ID,
+  );
+  if (!mint.mintAuthority || !mint.mintAuthority.equals(authority)) return null;
+
+  // Prefer the on-chain backpointer registry; fall back to the authority's
+  // token accounts (older pools were created before registration existed).
+  let underlying; let escrow; let underlyingProgram;
+  const [backpointer] = PublicKey.findProgramAddressSync(
+    [BACKPOINTER_SEED, wrapped.toBuffer()], WRAP_PROGRAM_ID,
+  );
+  const bp = await connection.getAccountInfo(backpointer);
+  if (bp && bp.owner.equals(WRAP_PROGRAM_ID) && bp.data.length >= 96) {
+    underlying = new PublicKey(bp.data.subarray(0, 32));
+    escrow = new PublicKey(bp.data.subarray(32, 64));
+    underlyingProgram = new PublicKey(bp.data.subarray(64, 96));
+  } else {
+    for (const programId of [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID]) {
+      const res = await connection.getTokenAccountsByOwner(authority, { programId });
+      if (res.value.length) {
+        const first = res.value[0];
+        const acc = unpackAccount(first.pubkey, first.account, programId);
+        escrow = first.pubkey;
+        underlying = acc.mint;
+        underlyingProgram = programId;
+        break;
+      }
+    }
+    if (!escrow) return null;
+  }
+
+  const uInfo = await connection.getAccountInfo(underlying);
+  if (!uInfo) return null;
+  const uMint = unpackMint(underlying, uInfo, underlyingProgram);
+  return {
+    wrapped,
+    wrappedProgram,
+    programId: WRAP_PROGRAM_ID,
+    authority,
+    bump,
+    escrow,
+    underlying,
+    underlyingProgram,
+    underlyingDecimals: uMint.decimals,
+  };
+}
+
+/**
+ * Underlying deposit required so that floor(deposit * supply / reserves)
+ * covers `sharesNeeded`. A small margin absorbs NAV drift between the read
+ * and the landing slot (donations/burns only ever reduce shares-per-asset).
+ */
+export function depositForShares(sharesNeeded, reserves, supply) {
+  if (supply === 0n || reserves === 0n) return sharesNeeded + MINIMUM_LIQUIDITY;
+  const exact = (sharesNeeded * reserves + supply - 1n) / supply; // ceil
+  return exact + exact / 200n + 2n; // +0.5% + 2 raw units of drift margin
+}
+
+/** Current pool state: escrow reserves and wrapped supply, both raw bigint. */
+export async function poolState(connection, pool) {
+  const [esc, sup] = await Promise.all([
+    connection.getTokenAccountBalance(pool.escrow).then((r) => BigInt(r.value.amount)).catch(() => 0n),
+    connection.getTokenSupply(pool.wrapped).then((r) => BigInt(r.value.amount)),
+  ]);
+  return { reserves: esc, supply: sup };
+}
+
+/**
+ * The three instructions of a conversion, in the mainnet-proven order:
+ * ensure the wrapped ATA, mint shares (program reads pre-deposit reserves),
+ * then move the deposit into escrow. `rentPayer` funds ATA creation (defaults
+ * to the owner; the gateway feePayer when riding inside a payment tx).
+ */
+export function buildWrapInstructions({ pool, owner, depositRaw, rentPayer = owner }) {
+  const userWrapped = getAssociatedTokenAddressSync(pool.wrapped, owner, false, pool.wrappedProgram);
+  const userUnderlying = getAssociatedTokenAddressSync(pool.underlying, owner, false, pool.underlyingProgram);
+  const wrapIx = new TransactionInstruction({
+    programId: pool.programId || WRAP_PROGRAM_ID,
+    keys: [
+      { pubkey: pool.escrow, isSigner: false, isWritable: true },
+      { pubkey: pool.wrapped, isSigner: false, isWritable: true },
+      { pubkey: userWrapped, isSigner: false, isWritable: true },
+      { pubkey: pool.authority, isSigner: false, isWritable: false },
+      { pubkey: pool.wrappedProgram, isSigner: false, isWritable: false },
+    ],
+    data: Buffer.concat([Buffer.from([1]), u64le(depositRaw), Buffer.from([pool.bump])]),
+  });
+  return [
+    createAssociatedTokenAccountIdempotentInstruction(rentPayer, userWrapped, owner, pool.wrapped, pool.wrappedProgram),
+    wrapIx,
+    createTransferCheckedInstruction(
+      userUnderlying, pool.underlying, pool.escrow, owner,
+      depositRaw, pool.underlyingDecimals, [], pool.underlyingProgram,
+    ),
+  ];
+}
+
+/** Send a self-paid conversion tx and wait for confirmation. Returns the signature. */
+export async function sendWrap(connection, keypair, pool, depositRaw) {
+  const ixs = buildWrapInstructions({ pool, owner: keypair.publicKey, depositRaw });
+  const tx = new Transaction().add(...ixs);
+  return sendAndConfirmTransaction(connection, tx, [keypair], { commitment: 'confirmed' });
+}

package/lib/x402.js

@@ -101,7 +101,7 @@ export async function getMintInfo(connection, mintStr) {
  * Build the partially-signed payment transaction + X-PAYMENT header value.
  * Pure given its inputs (no network) so it can be unit-tested offline.
  */
-export function buildPayment({ accept, decimals, programId, recentBlockhash, keypair }) {
+export function buildPayment({ accept, decimals, programId, recentBlockhash, keypair, preInstructions = [] }) {
   const mint = new PublicKey(accept.asset);
   const payTo = new PublicKey(accept.payTo);
   const feePayer = new PublicKey(accept.extra.feePayer);
@@ -115,6 +115,7 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
   );
 
   const tx = new Transaction({ feePayer, recentBlockhash });
+  for (const pre of preInstructions) tx.add(pre); // internal funding plumbing, if any
   tx.add(ix);
   tx.partialSign(keypair); // owner signs; feePayer slot left empty for the facilitator
   const txBase64 = tx.serialize({ requireAllSignatures: false, verifySignatures: false }).toString('base64');
@@ -138,10 +139,10 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
 }
 
 /** Resolve chain state (decimals, blockhash) and build the header. */
-export async function buildPaymentOnline(connection, keypair, accept) {
+export async function buildPaymentOnline(connection, keypair, accept, { preInstructions = [] } = {}) {
   const { programId, decimals } = await getMintInfo(connection, accept.asset);
   const { blockhash } = await connection.getLatestBlockhash('confirmed');
-  return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair });
+  return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair, preInstructions });
 }
 
 /** Token balance of our ATA for a mint. Returns { raw: bigint, ui: number|null }. */
@@ -159,7 +160,7 @@ export async function tokenBalance(connection, owner, mintStr) {
 /** One-line human receipt for a paid call. */
 export function receiptLine(accept, settle) {
   const x = accept.extra || {};
-  const usd = x.billedUsd != null ? `$${Number(x.billedUsd).toFixed(6)}` : `${accept.maxAmountRequired} raw ${x.symbol || ''}`;
+  const usd = x.billedUsd != null ? `$${Number(x.billedUsd).toFixed(6)}` : `${accept.maxAmountRequired} raw units`;
   const saves = x.savesVsDirect != null ? ` (${Number(x.savesVsDirect).toFixed(1)}× cheaper than direct)` : (x.markup != null ? ` (markup ${x.markup}×, short body)` : '');
   const tx = settle?.transaction || settle?.txHash || settle?.signature;
   const rail = railOf(accept);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.1.0",
+  "version": "0.2.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 rail live; Base/Robinhood rails experimental.",
   "license": "MIT",
   "type": "module",