{
  "markdown": "# Z-ZERO MCP — Payment Infrastructure for Agentic Commerce (USDC on Base, gasless)\n\n[![MCP Badge](https://lobehub.com/badge/mcp/dempty-glitch-z-zero-mcp)](https://lobehub.com/mcp/dempty-glitch-z-zero-mcp)\n[![npm](https://img.shields.io/npm/v/z-zero-mcp-server)](https://www.npmjs.com/package/z-zero-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**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.\n\nZ-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**.\n\n```bash\nnpx z-zero-mcp-server\n```\n\n**What makes it different:**\n- 🔐 **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.\n- ⛽ **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.\n- 💳 **JIT single-use virtual cards** — amount-locked, 1-hour TTL, burned after a single use. Fiat fallback for the rest of the web.\n- 🧠 **Smart Routing + checkout intelligence** — `get_merchant_hints` serves platform-specific checkout playbooks (Shopify, Etsy, WooCommerce…).\n- ✍️ **Linked purpose + outcome** — the server signs the criteria the agent records at issuance. Before checkout, `execute_payment` hands those criteria back and requires a second call with `go` or `pause`; 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.\n- 🔄 **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.\n\n---\n\n## Live on Base Mainnet\n\n- ✅ Proof — real gasless USDC transfer on Base mainnet: [`0xdfd1f2f8…5d7a`](https://basescan.org/tx/0xdfd1f2f824e1232c3e03c52485332570ff01fbb0340c5571f699ed1218735d7a)\n- Onboarding is just \"deposit USDC\" — no seed phrases in the agent, no native gas token, no exchange account.\n\n---\n\n## How It Works\n\n```\n User            AI Agent              MCP Tools              Z-ZERO API\n  │                  │                      │                      │\n  │ \"Buy me this     │                      │                      │\n  │  Shopify item\"   │                      │                      │\n  ├─────────────────▶│                      │                      │\n  │                  │ read mcp://resources/sop (MANDATORY)        │\n  │                  ├─────────────────────▶│                      │\n  │                  │◀── platform rules ───┤                      │\n  │                  │    + payment SOP     │                      │\n  │                  │                      │                      │\n  │                  │ get_merchant_hints(\"_platform_shopify\")     │\n  │                  ├─────────────────────▶│  GET /checkout-hints │\n  │                  │                      ├─────────────────────▶│\n  │                  │◀── pre_steps+notes ──┤◀──── hints data ─────┤\n  │                  │                      │                      │\n  │                  │ (fills shipping form, reaches payment page) │\n  │                  │                      │                      │\n  │                  │ request_payment_token(amount, cart, criteria)│\n  │                  ├─────────────────────▶│                      │\n  │                  │◀── temp_auth token ──┤   (1-hour TTL)       │\n  │                  │                      │                      │\n  │                  │ execute_payment(token, checkout_url)        │\n  │                  ├─────────────────────▶│                      │\n  │                  │◀── purpose_check ────┤  (nothing charged)   │\n  │                  │  compare locked criteria with final page    │\n  │                  │                      │                      │\n  │                  │ execute_payment(..., recheck: go | pause)   │\n  │                  ├─────────────────────▶│                      │\n  │                  │      pause → no card is filled              │\n  │                  │      go → Playwright fills + submits,       │\n  │                  │      then burns token if confirmed 🔥       │\n  │                  │◀──── ✅ success ─────┤                      │\n  │ \"Done! Your item │                      │                      │\n  │  is ordered.\"    │                      │                      │\n  │◀─────────────────┤                      │                      │\n```\n\n*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.*\n\n> **Crypto checkout branch:** when `auto_pay_checkout` detects a crypto-native checkout (EIP-681), it skips the card flow entirely and settles as a **gasless USDC transfer on Base** — see above.\n\n---\n\n## Why Z-ZERO\n\nZ-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).\n\n**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:\n\n- **Shared checkout intelligence** — every transaction (and every failure) makes the network smarter.\n- **An open standard for agent payments** — any agent platform plugs in via MCP; any rail (cards, USDC, x402) can be added.\n- **KYA — Know Your Agent** — verifiable agent reputation. The question isn't \"can this agent pay?\" but \"should you trust it to?\"\n\n📖 Full vision & architecture: [The Z-Zero Whitebook](https://z-zero.xyz/whitebook)\n\n---\n\n## Quick Install (Recommended)\n\n```bash\nnpx z-zero-mcp-server\n```\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"z-zero\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"z-zero-mcp-server@latest\"],\n      \"env\": {\n        \"Z_ZERO_API_KEY\": \"zk_live_your_passport_key_here\"\n      }\n    }\n  }\n}\n```\n\nGet your Passport Key at: **[z-zero.xyz/dashboard/agents](https://z-zero.xyz/dashboard/agents)**\n\n---\n\n## Security: rotate-on-connect (v1.5.0+)\n\nThe key you copy from the dashboard (or paste into a chat) is only a **one-time bootstrap ticket**.\nThe moment your agent connects with it, the MCP server silently swaps it for a fresh key:\n\n- The fresh key travels **server → MCP process → disk** and is stored in `~/.z-zero/credentials` (mode `0600`). It never appears in any LLM conversation, tool result, or config file.\n- The pasted key is **dead within seconds** — a copy living in a chat transcript, clipboard, or screenshot can no longer be used by anyone.\n- On startup the MCP loads the key from `~/.z-zero/credentials` first; the `Z_ZERO_API_KEY` env var is only a bootstrap fallback.\n\n**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.\n\nOlder self-hosted backends without the rotate endpoint keep working — the pasted key simply stays active as before.\n\n---\n\n## Requirements\n\n- **Node.js v18+** — [nodejs.org](https://nodejs.org)\n- **Passport Key** — starts with `zk_live_`, get it from the dashboard above\n\n---\n\n## Available MCP Tools\n\n### Group 1 — Wallet Config (Passive)\n\n| Tool | Description |\n|------|-------------|\n| `list_cards` | List all virtual card aliases and balances |\n| `check_balance` | Check spendable USD balance for a card alias |\n| `get_deposit_addresses` | Get your Base deposit address to top up with USDC (stablecoin on Base) |\n| `set_api_key` | Activate a new Passport Key instantly, no restart needed |\n| `show_api_key_status` | Check if a Passport Key is currently loaded (prefix only) |\n\n### Group 2 — Manual Card Payment (Active)\n\n| Tool | Description |\n|------|-------------|\n| `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 |\n| `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 |\n| `cancel_payment_token` | Cancel an unused token and refund to wallet |\n| `request_human_approval` | Pause and request human confirmation before proceeding |\n\n### Group 3 — Smart Autopilot\n\n| Tool | Description |\n|------|-------------|\n| `auto_pay_checkout` | Fully autonomous checkout — auto-detects Web3 or Fiat and completes payment |\n| `get_merchant_hints` | Fetch platform-specific checkout playbook (pre-steps + selectors) from Knowledge Base |\n| `report_checkout_fail` | Report a failed checkout with a **structured `failure_class`** (14-class enum) — feeds the self-healing loop |\n| `verify_receipt` | Verify a signed receipt by id — prove a purchase happened instead of claiming it |\n\n> 📖 **Note:** Version checking is handled automatically in each API call. No separate tool needed.\n\n---\n\n## Agent primitives (v1.9.0)\n\nFour linked records and controls an agent can use here that it cannot get from a normal virtual card alone.\n\n### 1. Signed intent — the card knows what it is for\n\nPass the cart when you request a token:\n\n```jsonc\nrequest_payment_token({\n  card_alias: \"Card_01\",\n  amount: 44.00,\n  merchant: \"etsy.com\",\n  cart: [{ title: \"Ceramic mug — matte white\", qty: 2, unit_price: 18.50 }],\n  ship_to: \"12 Nguyen Hue, District 1, Ho Chi Minh City, VN\",\n  criteria: {\n    source: \"user_described\",\n    items: [\n      { key: \"item\", stated: \"two matte-white ceramic mugs\" },\n      { key: \"max_total\", stated: \"no more than $44 delivered\" }\n    ]\n  }\n})\n```\n\nZ-ZERO signs that statement (EIP-191) during issuance. It is a tamper-evident\nrecord of the criteria the agent supplied as the owner's instruction — not an\nindependent proof that the human personally approved every line. The shipping\naddress is stored as a hash, never raw.\n\n**Before you request a token, compare the checkout page with what the user actually\nasked for** — same items, same quantity, same variant, same destination. A mismatch\nyou catch there costs nothing. After the token, it costs a card.\n\n### 2. Purpose check — read first, then declare `go` or `pause`\n\n`execute_payment` is deliberately a two-call tool:\n\n```jsonc\n// Call 1 — omit recheck. No browser, PAN, or charge.\nexecute_payment({ token, checkout_url, actual_amount: 44.00 })\n// → { status: \"purpose_check\", nothing_charged: true, owner_asked_for: ... }\n\n// Call 2 — describe the final page and make an explicit decision.\nexecute_payment({\n  token,\n  checkout_url,\n  actual_amount: 44.00,\n  recheck: {\n    page_shows: \"2 matte-white mugs, delivered total $44.00\",\n    decision: \"go\"\n  }\n})\n```\n\nUse `decision: \"pause\"` when anything differs. The card is not filled and the\ntoken remains active and refundable. On `go`, the checkout runs; if the merchant\nconfirms the order, the declaration is sealed into the signed receipt with the\noutcome. The platform records what the agent declared; it does not independently\ninspect the page or certify that the declaration was true.\n\n### 3. Signed receipt — prove the purchase, don't claim it\n\nOn a confirmed payment you get back:\n\n```jsonc\n\"signed_receipt\": {\n  \"receipt_id\": \"8ea36791-…\",\n  \"receipt_hash\": \"0x…\",\n  \"match\": { \"total\": \"over\", \"domain\": \"ok\" },\n  \"diff\":  [{ \"field\": \"total\", \"expected\": 44.00, \"observed\": 46.75 }],\n  \"verify_url\": \"https://z-zero.xyz/receipt/8ea36791-…\"\n}\n```\n\n`diff` is the part that matters: it is what the merchant actually did versus what\nwas authorized. Share `verify_url` with the user — the page is public and anyone\ncan check it. Verification is three checks: the signature is valid, the signer is\nZ-ZERO, and the fields shown still hash to what was signed (so editing the record\nafterwards is detectable, including by us).\n\n**What a valid receipt does and does not prove.** It proves the record is signed by\nZ-ZERO and unaltered. It does not by itself prove the merchant charged what the\nreceipt says — most fields start life as the agent's reading of a web page. Every\nreceipt therefore carries `provenance` per field: `zzero_issued` (the limit we set),\n`issuer_captured` (confirmed by the card issuer's capture webhook — settlement\nevidence), `agent_reported` (unverified), `human_verified`. Until the capture webhook\nlands, this is a **signed execution receipt**, not settlement proof, and it says so.\n\n### 4. Structured failure classes — every failure teaches the network\n\n`report_checkout_fail` takes a fixed enum, not free text:\n\n`card_declined_issuer` · `card_declined_bin_block` · `avs_mismatch` · `3ds_required` ·\n`bot_detected` · `form_changed` · `price_changed` · `out_of_stock` ·\n`shipping_unsupported` · `login_required` · `timeout` · `outcome_unconfirmed` ·\n`intent_mismatch` · `unknown`\n\nFailed runs are also labeled automatically from the browser outcome, so the network\nlearns even when nobody remembers to report. Card numbers are redacted at capture —\nthey never reach a log, screenshot or DOM dump.\n\n---\n\n## REST API Reference\n\nThe Z-ZERO backend is hosted at `https://z-zero.xyz`. All endpoints require a `Bearer` token using your Passport Key.\n\n> ⚠️ **Use the MCP tools above instead of calling REST directly.** If you must call REST, use the exact paths below.\n\n### `GET /api/tokens/cards`\nReturns your card list, balance, and deposit addresses.\n```bash\ncurl -X GET \"https://z-zero.xyz/api/tokens/cards\" \\\n  -H \"Authorization: Bearer zk_live_your_key\"\n```\n\n**Aliases (also work):**\n- `GET /api/v1/cards` ← for agents that guess REST-style paths\n\n### `POST /api/tokens/issue`\nIssue a JIT payment token.\n\n### `POST /api/tokens/resolve`\nResolve a token to card data (server-side only).\n\n### `POST /api/tokens/burn`\nBurn a used token.\n\n### `POST /api/tokens/cancel`\nCancel an unused token (refunds balance).\n\n---\n\n## Troubleshooting\n\n### \"Z_ZERO_API_KEY is missing\"\n1. Go to [z-zero.xyz/dashboard/agents](https://z-zero.xyz/dashboard/agents)\n2. Copy your Passport Key (starts with `zk_live_`)\n3. Add it to your config as `Z_ZERO_API_KEY`\n4. **Restart** Claude Desktop / Cursor\n\n### \"Invalid API Key\" (401)\n- Double-check you copied the full key (e.g. `zk_live_c0g3l`)\n- Make sure there are no extra spaces or line breaks\n\n### \"404 Not Found\" on `/api/v1/cards`\n- This is a legacy path alias — it should now work. If not, use `/api/tokens/cards` directly.\n\n---\n\n*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.*\n",
  "bytes": 15874,
  "sha": "c414ac20a9a8efe4f65aa8ac92851253bcf2620b3b8f86f98f1a82c8249b4a6e",
  "repo_slug": "dempty-glitch/z-zero-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dempty_glitch_z_zero_mcp_c6414c3a/readme"
}