z-zero-mcp

Z-ZERO MCP — 面向 Agent Commerce 的支付基础设施（Base 上的 USDC，无 Gas）

如今的 AI Agent 可以规划、推理和编写代码，却对财务一无所知。 它们无法持有资金、付款，也无法证明自己的可信度。每次购买仍然需要人类复制粘贴信用卡号。

Z-ZERO 解决了这个问题。一个 MCP 服务为你的 Agent（Claude、Cursor，以及任何兼容 MCP 的客户端）提供两种支付通道——用于加密原生结账的 Base 上免 Gas 的 USDC，以及适用于 99% 仅接受银行卡的网站的 JIT 一次性虚拟卡——同时模型永远看不到真实卡号。

npx z-zero-mcp-server

它的独特之处：

• 🔐 零信任设计——AI 永远看不到 PAN、CVV 或有效期。卡片数据仅存在于 RAM 中，在最后一步通过 Playwright 注入，随后立即清除。
• ⛽ Base 上免 Gas 的 USDC——自动检测加密原生结账（EIP-681），并通过 Coinbase Paymaster 赞助，以免 Gas 的 USDC 转账完成结算。Agent 只持有 USDC——不需要 ETH，也没有 Gas 操作体验。**需主动启用：**除非设置 Z_ZERO_ENABLE_WEB3_PAY=1，否则默认关闭，因为无法撤销向从网页读取的地址进行的链上转账。
• 💳 JIT 一次性虚拟卡——锁定金额，有效期为 1 小时，使用一次后即销毁。适用于其他网站的法币支付备用方案。
• 🧠 智能路由 + 结账智能——get_merchant_hints 提供针对特定平台的结账操作指南（Shopify、Etsy、WooCommerce……）。
• ✍️ 关联用途 + 结果——服务会对 Agent 在发卡时记录的标准进行签名。结账前，execute_payment 会返回这些标准，并要求再次调用时提供 go 或 pause；确认购买后，答案会写入签名收据。该记录可供检查，但不会假装平台判定了 Agent 是否如实陈述。
• 🔄 结构化失败标签——结账失败会自动标记为固定的 14 类 failure_class（并非只有 Agent 记得报告时才标记），并作为证据存入商户知识库。只有后续结果或审核核实了事实后，这些事实才会晋升为共享提示。

---

已在 Base 主网上线

• ✅ 证明 — Base 主网上真实的免 Gas USDC 转账：0xdfd1f2f8…5d7a
• 入门只需“存入 USDC”——Agent 无需助记词，无需原生 Gas 代币，也无需交易所账户。

---

工作原理

 User            AI Agent              MCP Tools              Z-ZERO API
  │                  │                      │                      │
  │ "Buy me this     │                      │                      │
  │  Shopify item"   │                      │                      │
  ├─────────────────▶│                      │                      │
  │                  │ read mcp://resources/sop (MANDATORY)        │
  │                  ├─────────────────────▶│                      │
  │                  │◀── platform rules ───┤                      │
  │                  │    + payment SOP     │                      │
  │                  │                      │                      │
  │                  │ get_merchant_hints("_platform_shopify")     │
  │                  ├─────────────────────▶│  GET /checkout-hints │
  │                  │                      ├─────────────────────▶│
  │                  │◀── pre_steps+notes ──┤◀──── hints data ─────┤
  │                  │                      │                      │
  │                  │ (fills shipping form, reaches payment page) │
  │                  │                      │                      │
  │                  │ request_payment_token(amount, cart, criteria)│
  │                  ├─────────────────────▶│                      │
  │                  │◀── temp_auth token ──┤   (1-hour TTL)       │
  │                  │                      │                      │
  │                  │ execute_payment(token, checkout_url)        │
  │                  ├─────────────────────▶│                      │
  │                  │◀── purpose_check ────┤  (nothing charged)   │
  │                  │  compare locked criteria with final page    │
  │                  │                      │                      │
  │                  │ execute_payment(..., recheck: go | pause)   │
  │                  ├─────────────────────▶│                      │
  │                  │      pause → no card is filled              │
  │                  │      go → Playwright fills + submits,       │
  │                  │      then burns token if confirmed 🔥       │
  │                  │◀──── ✅ success ─────┤                      │
  │ "Done! Your item │                      │                      │
  │  is ordered."    │                      │                      │
  │◀─────────────────┤                      │                      │

AI Agent 从不接触卡片数据——它只处理一次性令牌。真实卡片信息由 Playwright 在最后一步注入，并从 RAM 中清除。

**加密结账分支：**当 auto_pay_checkout 检测到加密原生结账（EIP-681）时，会完全跳过银行卡流程，并通过 Base 上免 Gas 的 USDC 转账完成结算——见上文。默认关闭；设置 Z_ZERO_ENABLE_WEB3_PAY=1 即可启用。

---

为什么选择 Z-ZERO

Z-ZERO 不是代购机器人，而是面向 Agent 商务时代的支付基础设施（预计到 2030 年，Agent 交易规模将达到 1.5T 美元——Juniper Research）。

如今，互联网是为人类打造的：Agent 必须填写表单、点击按钮，而且每笔交易仍然需要人类提供银行卡。Z-ZERO 现在就能解决这个问题——即时生成的一次性虚拟卡 + Base 上免 Gas 的 USDC，并将卡片数据与模型隔离。未来，Agent 支付将成为标准化协议——而我们一路构建的成果，才是长期价值所在：

• 共享结账智能——每笔交易（以及每次失败）都会让整个网络变得更智能。
• 面向 Agent 支付的开放标准——任何 Agent 平台都能通过 MCP 接入；任何支付通道（银行卡、USDC、x402）都可以添加。
• KYA——了解你的 Agent——可验证的 Agent 信誉。问题不在于“这个 Agent 能否付款？”，而在于“你是否应该信任它？”

📖 完整愿景与架构：Z-Zero 白皮书

---

快速安装（推荐）

npx z-zero-mcp-server

将以下内容添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "z-zero": {
      "command": "npx",
      "args": ["-y", "z-zero-mcp-server@latest"],
      "env": {
        "Z_ZERO_API_KEY": "zk_live_your_passport_key_here"
      }
    }
  }
}

在此获取 Passport Key：z-zero.xyz/dashboard/agents

---

安全性：连接时轮换密钥（v1.5.0+）

从控制面板复制（或粘贴到聊天中）的密钥只是一个一次性引导凭证。 Agent 使用它连接后，MCP 服务便会静默地将其替换为一个新密钥：

• 新密钥通过服务端 → MCP 进程 → 磁盘传递，并存储在 ~/.z-zero/credentials（模式为 0600）中。它绝不会出现在任何大模型对话、工具结果或配置文件中。
• 粘贴的密钥会在几秒内失效——聊天记录、剪贴板或截图中的副本都无法再被任何人使用。
• 启动时，MCP 会优先从 ~/.z-zero/credentials 加载密钥；Z_ZERO_API_KEY 环境变量仅作为引导备用项。

一个密钥 = 一台机器。 同一台机器上的所有 Agent（Claude Desktop、Claude Code、Cursor 等）共享同一 MCP 安装和同一个凭证文件——安装一次，所有 Agent 都能付款。使用复制的密钥连接另一台机器会触发密钥轮换，从而立即断开原机器的连接。这是有意设计的：既能阻止密钥共享，也能充当入侵警报——如果你的 Agent 突然无法通过身份验证，说明有人使用了你的密钥；请前往控制面板撤销密钥。

不支持密钥轮换端点的旧版可自托管后端仍可正常工作——粘贴的密钥会像以前一样继续有效。

---

要求

• Node.js v18+ — nodejs.org
• Passport Key — 以 zk_live_ 开头，可从上述控制面板获取

---

可用的 MCP 工具

第 1 组 — 钱包配置（被动）

工具	描述
list_cards	列出所有虚拟卡别名及余额
check_balance	查询指定卡片别名的可用美元余额
get_deposit_addresses	获取你的 Base 存款地址，以便使用 USDC（Base 上的稳定币）充值
set_api_key	即时启用新的 Passport Key，无需重启
show_api_key_status	检查当前是否已加载 Passport Key（仅显示前缀）

第 2 组 — 手动银行卡付款（主动）

工具	描述
request_payment_token	为指定金额签发即时生成的一次性虚拟卡令牌（有效期 1 小时）。传入 cart、criteria 和 ship_to，创建已签名的签发记录
execute_payment	**需要调用两次：**第一次不带 recheck，返回锁定的条件且不扣款；第二次传入 recheck: { page_shows, decision: go|pause }。选择 pause 不会填写卡片信息；确认选择 go 后会返回已签名的收据
cancel_payment_token	取消未使用的令牌，并将款项退回钱包
request_human_approval	暂停操作并请求人工确认，然后再继续

第 3 组 — 智能自动驾驶

工具	描述
auto_pay_checkout	全自动结账 — 签发 JIT 卡并完成付款（仅当 Z_ZERO_ENABLE_WEB3_PAY=1 时支持加密货币结账）
get_merchant_hints	从 Knowledge Base 获取平台专属的结账指南（前置步骤 + 选择器）
report_checkout_fail	使用结构化的 failure_class（14 类枚举）报告结账失败 — 为自我修复循环提供数据
verify_receipt	按 ID 验证已签名的收据 — 证明购买确已发生，而非仅声称购买成功

📖 注意： 每次 API 调用都会自动检查版本，无需单独使用工具。

---

Agent 基本功能（v1.9.0）

这里有四种关联记录和控件，Agent 可以使用，而普通虚拟卡本身不具备这些功能。

1. 已签名意图 — 卡片知道它的用途

申请令牌时传入购物车：

request_payment_token({
  card_alias: "Card_01",
  amount: 44.00,
  merchant: "etsy.com",
  cart: [{ title: "Ceramic mug — matte white", qty: 2, unit_price: 18.50 }],
  ship_to: "12 Nguyen Hue, District 1, Ho Chi Minh City, VN",
  criteria: {
    source: "user_described",
    items: [
      { key: "item", stated: "two matte-white ceramic mugs" },
      { key: "max_total", stated: "no more than $44 delivered" }
    ]
  }
})

Z-ZERO 会在签发过程中对该声明进行签名（EIP-191）。这是一份防篡改记录，记录了 Agent 根据所有者指示提供的条件 — 但不能独立证明人类亲自批准了每一项。配送地址仅以哈希形式存储，不会保存原始地址。

申请令牌前，请将结账页面与用户的实际要求进行比对 — 商品、数量、款式和目的地都必须一致。在这一步发现不符，不会产生任何代价。令牌签发后，代价就是一张卡。

2. 用途检查 — 先读取，再声明 go 或 pause

execute_payment 刻意设计为一个分两次调用的工具：

// Call 1 — omit recheck. No browser, PAN, or charge.
execute_payment({ token, checkout_url, actual_amount: 44.00 })
// → { status: "purpose_check", nothing_charged: true, owner_asked_for: ... }

// Call 2 — describe the final page and make an explicit decision.
execute_payment({
  token,
  checkout_url,
  actual_amount: 44.00,
  recheck: {
    page_shows: "2 matte-white mugs, delivered total $44.00",
    decision: "go"
  }
})

如有任何不同，请使用 decision: "pause"。卡片不会填写，令牌仍然有效且可退款。选择 go 后，结账流程将继续；如果商家确认订单，该声明及其结果会一并封存在已签名的收据中。平台会记录 Agent 所作的声明，但不会独立检查页面，也不会认证该声明是否属实。

3. 已签名收据 — 证明购买，而非仅声称购买

付款确认后，你会收到：

"signed_receipt": {
  "receipt_id": "8ea36791-…",
  "receipt_hash": "0x…",
  "match": { "total": "over", "domain": "ok" },
  "diff":  [{ "field": "total", "expected": 44.00, "observed": 46.75 }],
  "verify_url": "https://z-zero.xyz/receipt/8ea36791-…"
}

关键在于 diff：它显示商家实际执行的操作与获授权内容之间的差异。将 verify_url 分享给用户 — 该页面是公开的，任何人都可以查看。验证包含三项检查：签名有效、签名者是 Z-ZERO，以及显示的字段仍与签名内容的哈希相符（因此之后修改记录可以被发现，我们也能发现）。

有效收据能证明和不能证明的内容。 它能证明记录由 Z-ZERO 签名且未被篡改。但仅凭收据本身，无法证明商家实际扣款金额与收据所述一致 — 大多数字段最初都是 Agent 对网页内容的读取结果。因此，每张收据都会为各字段标注 provenance：zzero_issued（我们设定的限额）、issuer_captured（由发卡机构的扣款确认 webhook 确认 — 结算证据）、agent_reported（未经验证）、human_verified。在扣款确认 webhook 到达之前，这只是已签名的执行收据，并非结算证明；收据会明确说明这一点。

4. 结构化失败类别 — 每次失败都会让网络有所改进

report_checkout_fail 接受固定枚举，而非自由文本：

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

系统还会根据浏览器结果自动标记失败运行，因此即使无人记得报告，网络也能持续学习。捕获时会对卡号进行脱敏 — 它们绝不会出现在日志、屏幕截图或 DOM 转储中。

---

REST API 参考

Z-ZERO 后端托管于 https://z-zero.xyz。所有端点都需要使用 Passport Key 的 Bearer 令牌。

⚠️ 请使用上方的 MCP 工具，而不是直接调用 REST。 如果必须调用 REST，请使用下方列出的确切路径。

GET /api/tokens/cards

返回你的卡片列表、余额和存款地址。

curl -X GET "https://z-zero.xyz/api/tokens/cards" \
  -H "Authorization: Bearer zk_live_your_key"

别名（同样可用）：

• GET /api/v1/cards ← 适用于猜测 REST 风格路径的 Agent

POST /api/tokens/issue

签发 JIT 支付令牌。

POST /api/tokens/resolve

将令牌解析为卡片数据（仅限服务端）。

POST /api/tokens/burn

销毁已使用的令牌。

POST /api/tokens/cancel

取消未使用的令牌（退还余额）。

---

故障排查

“缺少 Z_ZERO_API_KEY”

1. 前往 z-zero.xyz/dashboard/agents
2. 复制你的 Passport Key（以 zk_live_ 开头）
3. 将其作为 Z_ZERO_API_KEY 添加到配置中
4. 重启 Claude Desktop / Cursor

“API Key 无效”（401）

• 确认已复制完整密钥（例如 zk_live_c0g3l）
• 确保没有多余的空格或换行符

/api/v1/cards 返回“404 Not Found”

• 这是一个旧版路径别名——现在应该可以使用。如果不行，请直接使用 /api/tokens/cards。

---

安全性：你粘贴的密钥不会被保留——Agent 首次连接时密钥便会轮换，新密钥仅存储在本地仅所有者可访问的文件中（~/.z-zero/credentials，模式为 0600），绝不会出现在任何大模型对话中。卡片数据仅在执行期间存在于易失性 RAM 中。