Z Zero MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Z Zero MCP listing page.
Z-ZERO MCP — Payment Infrastructure for Agentic Commerce (USDC on Base, gasless)
AI Agents today can plan, reason, and code — but they are financially blind. They cannot hold money, make payments, or prove their trustworthiness. Every purchase still requires a human to copy-paste a credit card number.
Z-ZERO fixes that. One MCP server gives your agent (Claude, Cursor, any MCP-compatible client) two payment rails — gasless USDC on Base for crypto-native checkouts, and JIT single-use virtual cards for the 99% of the web that only takes cards — while the model never sees a real card number.
What makes it different:
- 🔐 Zero-trust by design — the AI never sees PAN, CVV, or expiry. Card data exists only in RAM, injected via Playwright at the last step, then wiped.
- ⛽ Gasless USDC on Base — auto-detects crypto checkout (EIP-681) and settles as a gasless USDC transfer sponsored by Coinbase Paymaster. The agent holds only USDC — no ETH, no gas UX.
- 💳 JIT single-use virtual cards — amount-locked, 1-hour TTL, burned after a single use. Fiat fallback for the rest of the web.
- 🧠 Smart Routing + checkout intelligence —
get_merchant_hintsserves platform-specific checkout playbooks (Shopify, Etsy, WooCommerce…). - ✍️ Linked purpose + outcome — the server signs the criteria the agent records at issuance. Before checkout,
execute_paymenthands those criteria back and requires a second call withgoorpause; a confirmed purchase seals the answer into the signed receipt. The record is inspectable without pretending the platform judged whether the agent told the truth. - 🔄 Structured failure labels — failed checkouts are labeled with a fixed 14-class
failure_class(automatically, not only when an agent remembers to report) and stored as evidence for the merchant knowledge base. Facts are promoted into shared hints only after a later outcome or review verifies them.
Live on Base Mainnet
- ✅ Proof — real gasless USDC transfer on Base mainnet:
0xdfd1f2f8…5d7a - Onboarding is just "deposit USDC" — no seed phrases in the agent, no native gas token, no exchange account.
How It Works
The AI agent never touches card data — it only handles single-use tokens. Real card details are injected by Playwright at the last step and wiped from RAM.
Crypto checkout branch: when
auto_pay_checkoutdetects a crypto-native checkout (EIP-681), it skips the card flow entirely and settles as a gasless USDC transfer on Base — see above.
Why Z-ZERO
Z-ZERO is not a checkout bot — it's payment infrastructure for the agentic-commerce era (agentic transactions are projected to reach $1.5T by 2030 — Juniper Research).
Today, the web is built for humans: agents must fill forms and click buttons, and every purchase still needs a human's card. Z-ZERO solves that now — JIT single-use virtual cards + gasless USDC on Base, with card data isolated from the model. Tomorrow, agent payments become a standardized protocol — and what we build along the way is the long-term value:
- Shared checkout intelligence — every transaction (and every failure) makes the network smarter.
- An open standard for agent payments — any agent platform plugs in via MCP; any rail (cards, USDC, x402) can be added.
- KYA — Know Your Agent — verifiable agent reputation. The question isn't "can this agent pay?" but "should you trust it to?"
📖 Full vision & architecture: The Z-Zero Whitebook
Quick Install (Recommended)
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
Get your Passport Key at: z-zero.xyz/dashboard/agents
Security: rotate-on-connect (v1.5.0+)
The key you copy from the dashboard (or paste into a chat) is only a one-time bootstrap ticket. The moment your agent connects with it, the MCP server silently swaps it for a fresh key:
- The fresh key travels server → MCP process → disk and is stored in
~/.z-zero/credentials(mode0600). It never appears in any LLM conversation, tool result, or config file. - The pasted key is dead within seconds — a copy living in a chat transcript, clipboard, or screenshot can no longer be used by anyone.
- On startup the MCP loads the key from
~/.z-zero/credentialsfirst; theZ_ZERO_API_KEYenv var is only a bootstrap fallback.
One key = one machine. All agents on the same machine (Claude Desktop, Claude Code, Cursor, …) share the same MCP install and the same credentials file — install once, every agent can pay. Connecting a different machine with a copied key rotates it, which instantly disconnects the original machine. That is deliberate: it blocks key sharing and doubles as an intrusion alarm — if your agent suddenly fails auth, someone else used your key; go to the dashboard and revoke.
Older self-hosted backends without the rotate endpoint keep working — the pasted key simply stays active as before.
Requirements
- Node.js v18+ — nodejs.org
- Passport Key — starts with
zk_live_, get it from the dashboard above
Available MCP Tools
Group 1 — Wallet Config (Passive)
| Tool | Description |
|---|---|
list_cards | List all virtual card aliases and balances |
check_balance | Check spendable USD balance for a card alias |
get_deposit_addresses | Get your Base deposit address to top up with USDC (stablecoin on Base) |
set_api_key | Activate a new Passport Key instantly, no restart needed |
show_api_key_status | Check if a Passport Key is currently loaded (prefix only) |
Group 2 — Manual Card Payment (Active)
| Tool | Description |
|---|---|
request_payment_token | Issue a JIT single-use virtual-card token for a specific amount (1hr TTL). Pass cart, criteria, and ship_to to create the signed issuance record |
execute_payment | Two calls required: first without recheck returns the locked criteria and charges nothing; second supplies recheck: { page_shows, decision: go|pause }. pause does not fill the card; confirmed go returns a signed receipt |
cancel_payment_token | Cancel an unused token and refund to wallet |
request_human_approval | Pause and request human confirmation before proceeding |
Group 3 — Smart Autopilot
| Tool | Description |
|---|---|
auto_pay_checkout | Fully autonomous checkout — auto-detects Web3 or Fiat and completes payment |
get_merchant_hints | Fetch platform-specific checkout playbook (pre-steps + selectors) from Knowledge Base |
report_checkout_fail | Report a failed checkout with a structured failure_class (14-class enum) — feeds the self-healing loop |
verify_receipt | Verify a signed receipt by id — prove a purchase happened instead of claiming it |
📖 Note: Version checking is handled automatically in each API call. No separate tool needed.
Agent primitives (v1.9.0)
Four linked records and controls an agent can use here that it cannot get from a normal virtual card alone.
1. Signed intent — the card knows what it is for
Pass the cart when you request a token:
Z-ZERO signs that statement (EIP-191) during issuance. It is a tamper-evident record of the criteria the agent supplied as the owner's instruction — not an independent proof that the human personally approved every line. The shipping address is stored as a hash, never raw.
Before you request a token, compare the checkout page with what the user actually asked for — same items, same quantity, same variant, same destination. A mismatch you catch there costs nothing. After the token, it costs a card.
2. Purpose check — read first, then declare go or pause
execute_payment is deliberately a two-call tool:
Use decision: "pause" when anything differs. The card is not filled and the
token remains active and refundable. On go, the checkout runs; if the merchant
confirms the order, the declaration is sealed into the signed receipt with the
outcome. The platform records what the agent declared; it does not independently
inspect the page or certify that the declaration was true.
3. Signed receipt — prove the purchase, don't claim it
On a confirmed payment you get back:
diff is the part that matters: it is what the merchant actually did versus what
was authorized. Share verify_url with the user — the page is public and anyone
can check it. Verification is three checks: the signature is valid, the signer is
Z-ZERO, and the fields shown still hash to what was signed (so editing the record
afterwards is detectable, including by us).
What a valid receipt does and does not prove. It proves the record is signed by
Z-ZERO and unaltered. It does not by itself prove the merchant charged what the
receipt says — most fields start life as the agent's reading of a web page. Every
receipt therefore carries provenance per field: zzero_issued (the limit we set),
issuer_captured (confirmed by the card issuer's capture webhook — settlement
evidence), agent_reported (unverified), human_verified. Until the capture webhook
lands, this is a signed execution receipt, not settlement proof, and it says so.
4. Structured failure classes — every failure teaches the network
report_checkout_fail takes a fixed enum, not free text:
card_declined_issuer · card_declined_bin_block · avs_mismatch · 3ds_required ·
bot_detected · form_changed · price_changed · out_of_stock ·
shipping_unsupported · login_required · timeout · outcome_unconfirmed ·
intent_mismatch · unknown
Failed runs are also labeled automatically from the browser outcome, so the network learns even when nobody remembers to report. Card numbers are redacted at capture — they never reach a log, screenshot or DOM dump.
REST API Reference
The Z-ZERO backend is hosted at https://z-zero.xyz. All endpoints require a Bearer token using your Passport Key.
⚠️ Use the MCP tools above instead of calling REST directly. If you must call REST, use the exact paths below.
GET /api/tokens/cards
Returns your card list, balance, and deposit addresses.
Aliases (also work):
GET /api/v1/cards← for agents that guess REST-style paths
POST /api/tokens/issue
Issue a JIT payment token.
POST /api/tokens/resolve
Resolve a token to card data (server-side only).
POST /api/tokens/burn
Burn a used token.
POST /api/tokens/cancel
Cancel an unused token (refunds balance).
Troubleshooting
"Z_ZERO_API_KEY is missing"
- Go to z-zero.xyz/dashboard/agents
- Copy your Passport Key (starts with
zk_live_) - Add it to your config as
Z_ZERO_API_KEY - Restart Claude Desktop / Cursor
"Invalid API Key" (401)
- Double-check you copied the full key (e.g.
zk_live_c0g3l) - Make sure there are no extra spaces or line breaks
"404 Not Found" on /api/v1/cards
- This is a legacy path alias — it should now work. If not, use
/api/tokens/cardsdirectly.
Security: the key you paste is never kept — it rotates the moment your agent first connects, and the fresh key lives only in a local owner-only file (~/.z-zero/credentials, mode 0600), never in any LLM conversation. Card data exists only in volatile RAM during execution.