openzoo

Local x402-paying proxy + MCP server for 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:

export OPENAI_BASE_URL=http://localhost:8402/v1
export OPENAI_API_KEY=sk-openzoo

aider:

aider --openai-api-base http://localhost:8402/v1 --openai-api-key sk-openzoo --model openai/nvidia/nemotron-3.5-lightning

curl:

curl http://localhost:8402/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"nvidia/nemotron-3.5-lightning","messages":[{"role":"user","content":"hi"}]}'

OpenAI SDK (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):

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).

Related MCP server: x402-mcp

Use as MCP

The same package is an MCP server sharing the same wallet and payment core:

claude mcp add openzoo -- npx -y openzoo mcp

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:

{ "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).

• zoo_wallet — funding address, balances, and this session's receipts.

The demo

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), then fetches the live x402 quote for the same body — the quote is free:

quote: $0.009747 · pricing=counterfactual · direct would be $0.097474 · savesVsDirect=10.0×

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 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 (USDC + SOL + USD value) / 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.

The receipt names which base you got; extra.directUsd / extra.savesVsDirect let you check the math.

Payment rails

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

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