openzoo 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,123 @@
+# openzoo
+
+Local x402-paying proxy + MCP server for [openzoo.fun](https://openzoo.fun) — point **any** OpenAI-compatible harness (Cursor, Claude Code, aider, raw SDKs) at `localhost` and it pays the zoo per call from a local burner wallet. No account, no API key, no crypto knowledge required by your tools.
+
+```
+npx openzoo
+```
+
+That's it. First run generates a burner wallet at `~/.openzoo/wallet.json` (chmod 600), prints the funding address, and starts the proxy:
+
+```
+base_url = http://localhost:8402/v1
+api_key  = sk-openzoo        # any value works; the zoo takes payment, not keys
+```
+
+Every request forwards to the zoo. When the zoo answers `402 Payment Required`, the proxy reads the quote, signs a token transfer from your local wallet, retries with the `X-PAYMENT` header, and streams the response back — SSE included, unbuffered. Each payment prints a one-line receipt:
+
+```
+paid $0.002137 (9.5× cheaper than direct) · rail solana · tx 5Kd…
+```
+
+## 60-second quickstarts
+
+**Cursor** (Settings → Models → OpenAI API): set *Override OpenAI Base URL* to `http://localhost:8402/v1`, API key `sk-openzoo`. (Cursor Hobby can't BYOK; Pro can.)
+
+**Claude Code / any OpenAI-env tool:**
+```bash
+export OPENAI_BASE_URL=http://localhost:8402/v1
+export OPENAI_API_KEY=sk-openzoo
+```
+
+**aider:**
+```bash
+aider --openai-api-base http://localhost:8402/v1 --openai-api-key sk-openzoo --model openai/nvidia/nemotron-3.5-lightning
+```
+
+**curl:**
+```bash
+curl http://localhost:8402/v1/chat/completions -H 'Content-Type: application/json' \
+  -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).
+
+## Use as MCP
+
+The same package is an MCP server sharing the same wallet and payment core:
+
+```bash
+claude mcp add openzoo -- npx -y openzoo mcp
+```
+
+Other MCP hosts:
+
+```json
+{ "mcpServers": { "openzoo": { "command": "npx", "args": ["-y", "openzoo", "mcp"] } } }
+```
+
+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).
+- **`zoo_wallet`** — funding address, balances, and this session's receipts.
+
+## The demo
+
+```bash
+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×
+```
+
+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.
+
+## 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.
+- **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.
+
+## Honest pricing note
+
+Two bases, reported per call in the 402 (`extra.pricing`):
+- **Short prompts price at a markup** (3× provider cost) — there's nothing to spill, you're paying for passthrough.
+- **Big bodies price at a counterfactual discount** (~10× cheaper than buying the same call direct) — the zoo's leCore memory means it never forwards your whole body upstream, and passes the savings on. Measured numbers at [benches.openzoo.fun](https://benches.openzoo.fun).
+
+The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect` let you check the math.
+
+## Payment rails
+
+| rail | network | status |
+|---|---|---|
+| **Solana** (default) | `solana:5eykt…` | **live** — Token-2022 `TransferChecked`, partial-signed, gateway pays fees. Tested end-to-end against the production 402. |
+| 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. |
+
+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.)
+
+## Configuration
+
+| env | default | |
+|---|---|---|
+| `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_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_ENABLE_RH` | `0` | allow the Robinhood rail |
+
+## What's tested
+
+- Unit tests run against a **captured production 402 body** (`test/fixtures/live-402.json`): parsing, rail selection, and byte-level verification of the signed Solana transaction and the EVM typed-data payload.
+- Live-verified: `/v1/models` through the proxy (200), 402 parse + quote + wallet check against mainnet, on-chain mint/decimals read, and full payment construction (signed, not broadcast) against a production quote.
+- **Not yet live-verified: an actual settled paid call** — this session's wallet was unfunded, so settlement (the facilitator accepting the signed transfer) is untested from this client. The construction matches the gateway's own documented flow byte-for-byte.
+
+MIT

package/bin/openzoo.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+const cmd = process.argv[2] || 'proxy';
+
+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 demo       ~1M-token needle demo: direct refuses, the zoo answers
+  npx openzoo balance    wallet balances (yUSDCx / wTOKENx)
+  npx openzoo address    print the funding address
+  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)
+
+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_MAX_USD_PER_CALL (0.5)  OPENZOO_DEMO_MAX_USD (0.01)
+  OPENZOO_ENABLE_RH (0 — Robinhood Chain rail, experimental)`;
+
+async function main() {
+  switch (cmd) {
+    case 'proxy':
+    case 'start':
+      await (await import('../lib/proxy.js')).startProxy();
+      break;
+    case 'mcp':
+      await (await import('../lib/mcp.js')).startMcp();
+      break;
+    case 'demo':
+      await (await import('../lib/demo.js')).runDemo();
+      break;
+    case 'balance':
+      await (await import('../lib/info.js')).printBalance();
+      break;
+    case 'address':
+      (await import('../lib/info.js')).printAddress();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(HELP);
+      break;
+    default:
+      console.error(`unknown command: ${cmd}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`openzoo: ${err.message}`);
+  process.exit(1);
+});

package/lib/config.js

@@ -0,0 +1,15 @@
+import os from 'node:os';
+import path from 'node:path';
+
+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.
+  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).
+  maxUsdPerCall: Number(process.env.OPENZOO_MAX_USD_PER_CALL || 0.5),
+  // Demo will only actually pay if the quote is at or below this.
+  demoMaxUsd: Number(process.env.OPENZOO_DEMO_MAX_USD || 0.01),
+};

package/lib/demo.js

@@ -0,0 +1,104 @@
+import { config } from './config.js';
+import { PayClient } from './pay.js';
+import { parse402, pickAccept, tokenBalance } from './x402.js';
+
+const DEMO_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
+const NEEDLE = 'The zebra vault code is 7-ALPHA-9243.';
+const QUESTION = 'Somewhere in the document above there is a zebra vault code. What is it? Answer with just the code.';
+
+/** ~4 chars/token synthetic prose, distinct per paragraph (the zoo dedupes identical chunks). */
+function bigBody(targetTokens) {
+  const targetChars = targetTokens * 4;
+  const parts = [];
+  let chars = 0;
+  let i = 0;
+  const needleAt = Math.floor(targetChars * 0.7);
+  let planted = false;
+  while (chars < targetChars) {
+    const p = `Field report ${i}: sector ${i % 977} logged a routine survey at hour ${i % 24}. `
+      + `Instrument ${((i * 7919) % 65536).toString(16)} recorded nominal telemetry; archivist note ${i * 31 % 10007} `
+      + `filed under shelf ${i % 431}. Nothing unusual was observed during pass ${i}.`;
+    parts.push(p);
+    chars += p.length + 2;
+    if (!planted && chars >= needleAt) { parts.push(NEEDLE); planted = true; }
+    i += 1;
+  }
+  if (!planted) parts.push(NEEDLE);
+  return parts.join('\n\n');
+}
+
+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());
+}
+
+export async function runDemo() {
+  const client = new PayClient();
+  const { keypair, connection } = client;
+  const pub = client.address;
+
+  const tokens = Number(process.env.OPENZOO_DEMO_TOKENS || 965000);
+  console.log(`openzoo demo — model ${DEMO_MODEL}, ~${Math.round(tokens / 1000)}k-token body, one planted fact.`);
+  console.log('');
+  console.log('1) buying direct: a body this size does not run at all. OpenRouter returns:');
+  console.log('   "The input token count exceeds the maximum number of tokens allowed."');
+  console.log('   (recorded against the same model class, 2026-08-13 — benches.openzoo.fun)');
+  console.log('');
+
+  console.log('2) same body through the zoo — asking for the live x402 quote (the quote is free)...');
+  const doc = bigBody(tokens);
+  const bodyObj = {
+    model: DEMO_MODEL,
+    messages: [{ role: 'user', content: `${doc}\n\n${QUESTION}` }],
+    max_tokens: 32,
+    temperature: 0,
+  };
+  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}`
+    + (x.directUsd != null ? ` · direct would be $${Number(x.directUsd).toFixed(6)} · savesVsDirect=${Number(x.savesVsDirect).toFixed(1)}×` : ''));
+  console.log('');
+
+  // Decide what we can actually pay for under the demo cap.
+  let payBody = bodyObj;
+  let payAccept = accept;
+  if (Number(x.billedUsd) > config.demoMaxUsd) {
+    const fitTokens = Math.max(20000, Math.floor(tokens * (config.demoMaxUsd / Number(x.billedUsd)) * 0.8));
+    console.log(`   (full-size quote is over the demo cap $${config.demoMaxUsd} — paying for a ${Math.round(fitTokens / 1000)}k-token slice instead;`);
+    console.log('    set OPENZOO_DEMO_MAX_USD higher to pay for the whole thing)');
+    const doc2 = bigBody(fitTokens);
+    payBody = { ...bodyObj, messages: [{ role: 'user', content: `${doc2}\n\n${QUESTION}` }] };
+    const q2 = await quoteFor(payBody);
+    payAccept = pickAccept(q2, config.token);
+  }
+
+  const need = BigInt(payAccept.maxAmountRequired);
+  const bal = await tokenBalance(connection, keypair.publicKey, payAccept.asset);
+  if (bal.raw < need) {
+    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`.');
+    return;
+  }
+
+  console.log('3) paying and asking...');
+  const t0 = Date.now();
+  const { data, receipt } = await client.chat(payBody);
+  const secs = ((Date.now() - t0) / 1000).toFixed(1);
+  const answer = data?.choices?.[0]?.message?.content ?? '';
+  const usage = data?.usage || {};
+  console.log(`   answer (${secs}s): ${answer.trim()}`);
+  console.log(`   verdict: ${answer.includes('9243') ? 'HIT — the planted fact came back' : 'MISS'}`);
+  if (usage.gpu_tokens != null || usage.prompt_tokens != null) {
+    console.log(`   tokens the model actually read: ${usage.gpu_tokens ?? usage.prompt_tokens}${usage.spill_tokens ? ` (spilled: ${usage.spill_tokens})` : ''}`);
+  }
+  if (receipt) console.log(`   ${receipt.line}`);
+}

package/lib/evm.js

@@ -0,0 +1,77 @@
+import crypto from 'node:crypto';
+import { privateKeyToAccount } from 'viem/accounts';
+import { evmChainId } from './x402.js';
+
+/**
+ * EVM rails (Base eip155:8453; Robinhood Chain eip155:4663 behind OPENZOO_ENABLE_RH).
+ *
+ * Standard x402 v1 EVM "exact" scheme: an EIP-3009 transferWithAuthorization
+ * typed-data signature; the facilitator submits it. X-PAYMENT = base64 of
+ *   { x402Version: 1, scheme: "exact", network: "<as offered>",
+ *     payload: { signature, authorization: { from, to, value, validAfter, validBefore, nonce } } }
+ *
+ * IMPORTANT — the decimals landmine does not exist here BY CONSTRUCTION:
+ * authorization.value is the raw uint256 straight from maxAmountRequired.
+ * 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.
+ */
+export async function buildEvmPayment({ accept, evmPrivateKey }) {
+  const chainId = evmChainId(accept.network);
+  if (!chainId) throw new Error(`cannot parse EVM chain id from network ${accept.network}`);
+  const account = privateKeyToAccount(evmPrivateKey);
+
+  const now = Math.floor(Date.now() / 1000);
+  const authorization = {
+    from: account.address,
+    to: accept.payTo,
+    value: BigInt(accept.maxAmountRequired), // raw units from the 402 — never decimal-scaled
+    validAfter: 0n,
+    validBefore: BigInt(now + (accept.maxTimeoutSeconds || 600)),
+    nonce: `0x${crypto.randomBytes(32).toString('hex')}`,
+  };
+
+  const signature = await account.signTypedData({
+    domain: {
+      name: accept.extra?.name || 'USDC',
+      version: accept.extra?.version || '2',
+      chainId,
+      verifyingContract: accept.asset,
+    },
+    types: {
+      TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+      ],
+    },
+    primaryType: 'TransferWithAuthorization',
+    message: authorization,
+  });
+
+  const envelope = {
+    x402Version: 1,
+    scheme: accept.scheme,
+    network: accept.network,
+    payload: {
+      signature,
+      authorization: {
+        ...authorization,
+        value: authorization.value.toString(),
+        validAfter: authorization.validAfter.toString(),
+        validBefore: authorization.validBefore.toString(),
+      },
+    },
+  };
+  return {
+    header: Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64'),
+    ownerSignature: signature,
+    from: account.address,
+  };
+}

package/lib/info.js

@@ -0,0 +1,30 @@
+import { Connection } from '@solana/web3.js';
+import { privateKeyToAccount } from 'viem/accounts';
+import { config } from './config.js';
+import { loadOrCreateWallet } from './wallet.js';
+import { tokenBalance } from './x402.js';
+
+const YUSDCX = '6ZjjxcoicqM4nniddkuPVwew4PDwY3swbfHsGbCuLuTv';
+const WTOKENX = 'Bo7xBF7SY8EyUBPUxRP66SFafxoPf2n5uqiLjbxEebx9';
+
+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 Base/RH rails — untested: ${privateKeyToAccount(evmPrivateKey).address})`);
+}
+
+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),
+  ]);
+  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.');
+  }
+}

package/lib/mcp.js

@@ -0,0 +1,90 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { config } from './config.js';
+import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
+import { tokenBalance } from './x402.js';
+
+const YUSDCX = '6ZjjxcoicqM4nniddkuPVwew4PDwY3swbfHsGbCuLuTv';
+const WTOKENX = 'Bo7xBF7SY8EyUBPUxRP66SFafxoPf2n5uqiLjbxEebx9';
+const DEFAULT_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
+
+function text(obj) {
+  return { content: [{ type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2) }] };
+}
+
+/** `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' });
+
+  server.registerTool('zoo_ask', {
+    description:
+      'Ask a question through openzoo.fun, paying the x402 quote transparently from the local burner wallet. '
+      + 'The zoo puts leCore holographic memory in front of every model, so `corpus` can be a HUGE text body '
+      + '(hundreds of thousands to ~1M tokens) that the model itself would refuse — the zoo spills it and the '
+      + 'model reads only a few thousand tokens. Returns the answer plus a payment receipt '
+      + '(billedUsd, savesVsDirect, tokens actually read).',
+    inputSchema: {
+      prompt: z.string().describe('The question or instruction.'),
+      corpus: z.string().optional().describe('Optional big context body (document dump, logs, book...). Placed before the prompt.'),
+      model: z.string().optional().describe(`Model id from zoo_models. Default ${DEFAULT_MODEL}.`),
+      max_tokens: z.number().int().positive().optional().describe('Completion cap. Default 1024.'),
+    },
+  }, async ({ prompt, corpus, model, max_tokens }) => {
+    const content = corpus ? `${corpus}\n\n${prompt}` : prompt;
+    try {
+      const { data, receipt } = await client.chat({
+        model: model || DEFAULT_MODEL,
+        messages: [{ role: 'user', content }],
+        max_tokens: max_tokens || 1024,
+      });
+      const usage = data?.usage || {};
+      return text({
+        answer: data?.choices?.[0]?.message?.content ?? '',
+        receipt: receipt ? {
+          line: receipt.line,
+          billedUsd: receipt.billedUsd,
+          savesVsDirect: receipt.savesVsDirect,
+          pricing: receipt.pricing,
+          rail: receipt.rail,
+        } : 'free (no 402 issued)',
+        tokensRead: usage.gpu_tokens ?? usage.prompt_tokens ?? null,
+        spillTokens: usage.spill_tokens ?? null,
+      });
+    } catch (err) {
+      if (err instanceof UnderfundedError || err instanceof QuoteTooHighError) {
+        return { ...text(err.message), isError: true };
+      }
+      throw err;
+    }
+  });
+
+  server.registerTool('zoo_models', {
+    description: 'List the models the zoo serves, with per-token pricing (free endpoint, no payment).',
+    inputSchema: {},
+  }, async () => {
+    const r = await fetch(`${config.apiBase}/v1/models`);
+    return text(await r.json());
+  });
+
+  server.registerTool('zoo_wallet', {
+    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),
+    ]);
+    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 },
+      receipts: client.receipts.map((r) => ({ at: r.at, line: r.line })),
+    });
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`openzoo mcp on stdio — wallet ${client.address} — zoo ${config.apiBase}`);
+}

package/lib/pay.js

@@ -0,0 +1,116 @@
+import { Connection } from '@solana/web3.js';
+import { config } from './config.js';
+import { loadOrCreateWallet } from './wallet.js';
+import {
+  parse402, pickAccept, railOf, buildPaymentOnline, tokenBalance,
+  receiptLine, decodeSettleHeader,
+} from './x402.js';
+import { buildEvmPayment } from './evm.js';
+
+export class QuoteTooHighError extends Error {
+  constructor(billedUsd, quote) {
+    super(`openzoo: quote $${billedUsd} exceeds local cap $${config.maxUsdPerCall}. Raise OPENZOO_MAX_USD_PER_CALL to allow.`);
+    this.billedUsd = billedUsd;
+    this.quote = quote;
+  }
+}
+
+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}`);
+    this.accept = accept;
+    this.have = have;
+    this.address = address;
+  }
+}
+
+/**
+ * Shared x402-paying HTTP client — the single place payment happens.
+ * The proxy, the demo, and the MCP server all go through PayClient.fetch:
+ * request → 402 → pick rail (Solana first) → sign → retry with X-PAYMENT.
+ */
+export class PayClient {
+  constructor() {
+    const w = loadOrCreateWallet();
+    this.keypair = w.keypair;
+    this.evmPrivateKey = w.evmPrivateKey;
+    this.walletCreated = w.created;
+    this.walletPath = w.path;
+    this.connection = new Connection(config.rpcUrl, 'confirmed');
+    this.receipts = []; // last paid calls, newest last
+    this.allowRH = process.env.OPENZOO_ENABLE_RH === '1';
+  }
+
+  get address() { return this.keypair.publicKey.toBase58(); }
+
+  async buildPaymentFor(accept) {
+    const rail = railOf(accept);
+    if (rail === 'solana') {
+      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);
+      }
+      return buildPaymentOnline(this.connection, this.keypair, accept);
+    }
+    if (rail === 'base' || rail === 'evm' || (rail === 'robinhood' && this.allowRH)) {
+      return buildEvmPayment({ accept, evmPrivateKey: this.evmPrivateKey });
+    }
+    throw new Error(`no payment builder for rail ${rail} (network ${accept.network})`);
+  }
+
+  /**
+   * fetch that transparently pays a 402 once.
+   * Returns { response, paid, accept?, settle?, receipt? }.
+   * Throws QuoteTooHighError / UnderfundedError before any value moves.
+   */
+  async fetch(url, init = {}) {
+    const first = await fetch(url, init);
+    if (first.status !== 402) return { response: first, paid: false };
+
+    const quote = parse402(await first.json());
+    const accept = pickAccept(quote, config.token, { allowRH: this.allowRH });
+    const billedUsd = Number(accept?.extra?.billedUsd ?? NaN);
+    if (Number.isFinite(billedUsd) && billedUsd > config.maxUsdPerCall) {
+      throw new QuoteTooHighError(billedUsd, quote);
+    }
+
+    const payment = await this.buildPaymentFor(accept);
+    const response = await fetch(url, {
+      ...init,
+      headers: { ...(init.headers || {}), 'X-PAYMENT': payment.header },
+    });
+    const settle = decodeSettleHeader(response.headers.get('x-payment-response'))
+      || { signature: payment.ownerSignature };
+    const receipt = {
+      at: new Date().toISOString(),
+      line: receiptLine(accept, settle),
+      rail: railOf(accept),
+      billedUsd: accept.extra?.billedUsd,
+      savesVsDirect: accept.extra?.savesVsDirect,
+      pricing: accept.extra?.pricing,
+      symbol: accept.extra?.symbol,
+      amountRaw: accept.maxAmountRequired,
+      ok: response.ok,
+      status: response.status,
+    };
+    if (response.ok) {
+      this.receipts.push(receipt);
+      if (this.receipts.length > 20) this.receipts.shift();
+    }
+    return { response, paid: true, accept, settle, receipt };
+  }
+
+  /** POST a chat completion, paying as needed. Returns { data, receipt }. */
+  async chat(bodyObj) {
+    const { response, receipt } = await this.fetch(`${config.apiBase}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(bodyObj),
+    });
+    if (!response.ok) {
+      const text = (await response.text()).slice(0, 500);
+      throw new Error(`zoo returned HTTP ${response.status}: ${text}`);
+    }
+    return { data: await response.json(), receipt };
+  }
+}

package/lib/proxy.js

@@ -0,0 +1,110 @@
+import http from 'node:http';
+import { Readable } from 'node:stream';
+import { config } from './config.js';
+import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
+import { tokenBalance } from './x402.js';
+
+const HOP_BY_HOP = new Set([
+  'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade',
+  'proxy-authorization', 'proxy-connection', 'te', 'trailer', 'content-length',
+  // The harness's api key (sk-openzoo or anything) is accepted and dropped:
+  // the zoo takes payment, not keys.
+  'authorization',
+]);
+
+function upstreamHeaders(req) {
+  const out = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (!HOP_BY_HOP.has(k.toLowerCase())) out[k] = v;
+  }
+  return out;
+}
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const c of req) chunks.push(c);
+  return Buffer.concat(chunks);
+}
+
+/** Pipe an upstream fetch Response to the client, unbuffered (SSE-safe). */
+function relay(res, upstream) {
+  const headers = {};
+  upstream.headers.forEach((v, k) => {
+    if (!['transfer-encoding', 'connection', 'content-encoding', 'content-length'].includes(k)) headers[k] = v;
+  });
+  res.writeHead(upstream.status, headers);
+  if (!upstream.body) { res.end(); return Promise.resolve(); }
+  return new Promise((resolve) => {
+    const body = Readable.fromWeb(upstream.body);
+    body.on('error', () => res.destroy());
+    res.on('close', () => body.destroy());
+    body.on('end', resolve);
+    body.pipe(res);
+  });
+}
+
+function jsonErr(res, status, message, extraFields = {}) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ error: { message }, ...extraFields }));
+}
+
+export async function startProxy({ silent = false } = {}) {
+  const client = new PayClient();
+  const log = silent ? () => {} : (...a) => console.log(...a);
+
+  const server = http.createServer(async (req, res) => {
+    const url = `${config.apiBase}${req.url}`;
+    let bodyBuf;
+    try {
+      bodyBuf = await readBody(req);
+    } catch {
+      jsonErr(res, 400, 'bad request body');
+      return;
+    }
+    const init = { method: req.method, headers: upstreamHeaders(req) };
+    if (req.method !== 'GET' && req.method !== 'HEAD') init.body = bodyBuf;
+
+    try {
+      const { response, paid, receipt } = await client.fetch(url, init);
+      if (paid && receipt) log(receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`);
+      await relay(res, response);
+    } catch (err) {
+      if (err instanceof QuoteTooHighError) {
+        log(err.message);
+        jsonErr(res, 402, err.message, { quote: err.quote });
+      } else if (err instanceof UnderfundedError) {
+        log(err.message);
+        jsonErr(res, 402, err.message);
+      } else {
+        jsonErr(res, 502, `openzoo proxy error: ${err.message}`);
+      }
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(config.port, '127.0.0.1', resolve);
+  });
+
+  if (!silent) {
+    console.log(`openzoo proxy  ->  ${config.apiBase}`);
+    console.log(`listening on   http://localhost:${config.port}/v1`);
+    console.log('');
+    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})`);
+      if (!bal.raw) {
+        console.log('fund it with yUSDCx (wrap USDC at https://x402.accrue.fund/start) — a few cents goes a long way.');
+      }
+    } catch { /* RPC hiccup: balance is advisory */ }
+    console.log('');
+    console.log('point any OpenAI-compatible harness at:');
+    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 };
+}

package/lib/wallet.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { Keypair } from '@solana/web3.js';
+import { config } from './config.js';
+
+/**
+ * Local burner wallet at ~/.openzoo/wallet.json (chmod 600).
+ * Format v2: { "solana": [64 secret-key bytes], "evm": "0x<32-byte hex>" }
+ * Legacy format (bare 64-byte array, solana-keygen style) is migrated in place.
+ * Your keys never leave this machine — the zoo only ever sees signed transfers.
+ */
+export function loadOrCreateWallet() {
+  const p = config.walletPath;
+  let solanaBytes;
+  let evmKey;
+  let created = false;
+
+  if (fs.existsSync(p)) {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (Array.isArray(raw)) {
+      solanaBytes = Uint8Array.from(raw); // legacy: migrate below by adding an EVM key
+    } else {
+      solanaBytes = Uint8Array.from(raw.solana);
+      evmKey = raw.evm;
+    }
+  } else {
+    solanaBytes = Keypair.generate().secretKey;
+    created = true;
+  }
+  if (!evmKey) {
+    evmKey = `0x${crypto.randomBytes(32).toString('hex')}`;
+    fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(p, JSON.stringify({ solana: Array.from(solanaBytes), evm: evmKey }), { mode: 0o600 });
+  }
+  return {
+    keypair: Keypair.fromSecretKey(solanaBytes),
+    evmPrivateKey: evmKey,
+    created,
+    path: p,
+  };
+}

package/lib/x402.js

@@ -0,0 +1,188 @@
+import {
+  Connection,
+  PublicKey,
+  Transaction,
+} from '@solana/web3.js';
+import {
+  TOKEN_2022_PROGRAM_ID,
+  createTransferCheckedInstruction,
+  getAssociatedTokenAddressSync,
+  unpackMint,
+} from '@solana/spl-token';
+
+/**
+ * x402 protocol client for openzoo.fun (x402Version 1, Solana "exact" scheme).
+ *
+ * Captured live 402 shape (test/fixtures/live-402.json):
+ *   { x402Version: 1,
+ *     accepts: [ { scheme: "exact",
+ *                  network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+ *                  asset: "<mint>", maxAmountRequired: "<raw units, string>",
+ *                  payTo: "<wallet>", resource, description, maxTimeoutSeconds,
+ *                  extra: { facilitator, feePayer, symbol, billedUsd, tokenUsd,
+ *                           pricedAt, pricing: "markup"|"counterfactual",
+ *                           markup? , directUsd?, savesVsDirect? } } ],
+ *     error: "payment required", help: "..." }
+ *
+ * Payment: ONE Token-2022 TransferChecked (payer ATA -> payTo ATA) for exactly
+ * maxAmountRequired, feePayer = extra.feePayer (the gateway pays SOL fees),
+ * partial-signed by the payer, serialized requireAllSignatures=false, base64.
+ * X-PAYMENT header = base64 of
+ *   {"x402Version":1,"scheme":"exact","network":"<network>","payload":{"transaction":"<b64 tx>"}}
+ *
+ * NOTE: decimals are NOT in the 402 payload and the site's pasted prompt
+ * hardcoding "decimals = 6" is a known bug. We always read decimals from the
+ * mint account on-chain (see getMintInfo) — never hardcode.
+ */
+
+export function parse402(body) {
+  if (!body || body.x402Version !== 1 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+    throw new Error('not an x402 v1 payment-required body');
+  }
+  return body;
+}
+
+const EVM_NAME_CHAINS = { base: 8453, 'base-sepolia': 84532 };
+
+/** Which rail an accepts[] row settles on: 'solana' | 'base' | 'robinhood' | 'evm' | null. */
+export function railOf(accept) {
+  const net = accept?.network || '';
+  if (net.startsWith('solana:')) return 'solana';
+  const m = /^eip155:(\d+)$/.exec(net);
+  const chainId = m ? Number(m[1]) : EVM_NAME_CHAINS[net];
+  if (chainId === 8453 || chainId === 84532) return 'base';
+  if (chainId === 4663) return 'robinhood';
+  if (chainId) return 'evm';
+  return null;
+}
+
+export function evmChainId(network) {
+  const m = /^eip155:(\d+)$/.exec(network || '');
+  return m ? Number(m[1]) : EVM_NAME_CHAINS[network] ?? null;
+}
+
+/**
+ * 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.
+ */
+export function pickAccept(body, preferredSymbol, { allowRH = false } = {}) {
+  const rows = parse402(body).accepts.filter((a) => a?.scheme === 'exact');
+  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');
+  if (base.length) return base[0];
+  const evm = rows.filter((a) => railOf(a) === 'evm');
+  if (evm.length) return evm[0];
+  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)'
+    : 'no payable rail in 402 accepts[]');
+}
+
+const mintCache = new Map();
+
+/** Read the mint's owner program and decimals from chain. Cached per mint. */
+export async function getMintInfo(connection, mintStr) {
+  if (mintCache.has(mintStr)) return mintCache.get(mintStr);
+  const mint = new PublicKey(mintStr);
+  const info = await connection.getAccountInfo(mint);
+  if (!info) throw new Error(`mint ${mintStr} not found on chain (check OPENZOO_RPC)`);
+  const programId = info.owner; // TOKEN_PROGRAM_ID or TOKEN_2022_PROGRAM_ID
+  const parsed = unpackMint(mint, info, programId);
+  const out = { programId, decimals: parsed.decimals };
+  mintCache.set(mintStr, out);
+  return out;
+}
+
+/**
+ * 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 }) {
+  const mint = new PublicKey(accept.asset);
+  const payTo = new PublicKey(accept.payTo);
+  const feePayer = new PublicKey(accept.extra.feePayer);
+  const amount = BigInt(accept.maxAmountRequired);
+
+  const source = getAssociatedTokenAddressSync(mint, keypair.publicKey, false, programId);
+  const dest = getAssociatedTokenAddressSync(mint, payTo, true, programId);
+
+  const ix = createTransferCheckedInstruction(
+    source, mint, dest, keypair.publicKey, amount, decimals, [], programId,
+  );
+
+  const tx = new Transaction({ feePayer, recentBlockhash });
+  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');
+
+  const envelope = {
+    x402Version: 1,
+    scheme: accept.scheme,
+    network: accept.network,
+    payload: { transaction: txBase64 },
+  };
+  const header = Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+  const ownerSig = tx.signatures.find((s) => s.publicKey.equals(keypair.publicKey) && s.signature);
+  return {
+    header,
+    txBase64,
+    ownerSignature: ownerSig ? base58encode(ownerSig.signature) : null,
+    amount,
+    source,
+    dest,
+  };
+}
+
+/** Resolve chain state (decimals, blockhash) and build the header. */
+export async function buildPaymentOnline(connection, keypair, accept) {
+  const { programId, decimals } = await getMintInfo(connection, accept.asset);
+  const { blockhash } = await connection.getLatestBlockhash('confirmed');
+  return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair });
+}
+
+/** Token balance of our ATA for a mint. Returns { raw: bigint, ui: number|null }. */
+export async function tokenBalance(connection, owner, mintStr) {
+  try {
+    const { programId } = await getMintInfo(connection, mintStr);
+    const ata = getAssociatedTokenAddressSync(new PublicKey(mintStr), owner, false, programId);
+    const bal = await connection.getTokenAccountBalance(ata);
+    return { raw: BigInt(bal.value.amount), ui: bal.value.uiAmount };
+  } catch {
+    return { raw: 0n, ui: 0 };
+  }
+}
+
+/** 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 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);
+  return `paid ${usd}${saves}${rail ? ` · rail ${rail}` : ''}${tx ? ` · tx ${tx}` : ''}`;
+}
+
+/** Decode the server's X-PAYMENT-RESPONSE header (base64 JSON), if present. */
+export function decodeSettleHeader(headerValue) {
+  if (!headerValue) return null;
+  try {
+    return JSON.parse(Buffer.from(headerValue, 'base64').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Minimal base58 (bitcoin alphabet) — enough to print a signature.
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+function base58encode(bytes) {
+  let n = 0n;
+  for (const b of bytes) n = n * 256n + BigInt(b);
+  let out = '';
+  while (n > 0n) { out = B58[Number(n % 58n)] + out; n /= 58n; }
+  for (const b of bytes) { if (b === 0) out = '1' + out; else break; }
+  return out;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "openzoo",
+  "version": "0.1.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",
+  "bin": {
+    "openzoo": "bin/openzoo.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.4",
+    "viem": "^2.21.0",
+    "zod": "^3.24.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/staccDOTsol/openzoo.git"
+  },
+  "homepage": "https://openzoo.fun",
+  "keywords": [
+    "x402",
+    "openai",
+    "proxy",
+    "solana",
+    "llm",
+    "openzoo",
+    "payments"
+  ]
+}