一文读懂 x402 协议:vAPI Network 如何用 USDC 在 Base 上为 API 调用按次付费

原创2026-11-06 15:10:361,832 阅读

一文读懂 x402 协议:vAPI Network 如何用 USDC 在 Base 上为 API 调用按次付费

x402 协议是一套基于 HTTP 402 状态码的 API 支付标准,让程序和 AI Agent 能直接用 USDC 在 Base 链上为每一次 API 调用按次付费,而不必提前注册账号或充值订阅。vAPI Network 是一个开源、非托管的 x402 客户端,它帮你搜索、检查并安全支付这些付费 API。本文带你从零看懂 x402 的完整原理,以及它如何在 Base 上跑通。

💡 一句话理解:x402 = 给 API 装上"支付网关"。API 想收费就返回 402,客户端付了钱,API 才放行。

什么是 x402 协议:让 API 直接收钱的支付标准

传统调用付费 API,通常要先注册账号、申请 key、充值或订阅,对程序尤其对 AI Agent 来说非常麻烦——每个 API 都要走一遍人工流程。

x402 的思路更直接:

  • 收费即拦截:API 未收到支付时,返回 HTTP 状态码 402 Payment Required(而不是 403),并附上一份"报价单"。
  • 机器可读:报价单用标准 JSON 描述"付多少、付什么币、付到哪条链、付给哪个地址"。
  • 支付即放行:客户端按要求付款后重试,API 校验通过,返回正常结果。

这样,任何符合 x402 的 API 都能被任何客户端"即付即用",天然适合 Agent 为完成任务自动调用各种服务的场景。

x402 按次付费的 4 步流程

理解一次 API 调用如何变成一次 USDC 支付,是理解 x402 的核心。整个流程只有 4 步:

第 1 步:请求 API,收到 HTTP 402 报价

客户端先发起一次普通请求。因为没付钱,API 返回 402,并附上一份"挑战(challenge)"。它可能放在 PAYMENT-REQUIRED 响应头(base64 编码的 JSON),也可能直接在响应体里。解析与报价读取逻辑在 packages/core/src/x402.ts。

第 2 步:解析报价,锁定网络与金额

报价里的 accepts[] 数组列出了所有可选付款方式,每一项包含:

  • network:支付发生在哪条链(Base 主网标识为 eip155:8453)
  • asset:要付的币种(这里是 Base 上的 USDC,合约地址 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
  • amount:金额
  • payTo:收款地址(服务商自己)
  • maxTimeoutSeconds:授权有效期

这些 Base / USDC 的"标准身份"被硬编码校验,确保只接受真正的 Base USDC,防止被指向错误的代币。见 packages/core/src/x402-networks.ts。

第 3 步:用 EIP-3009 授权签名,而不是直接转账

这是 x402 很巧妙的一点:客户端不直接发交易,而是对一份 EIP-3009 TransferWithAuthorization 授权做签名,表示"我授权在有效期内、把这笔 USDC 转给这个地址"。

  • 授权内容包含 from、to、value、validBefore(最长约 10 分钟)和随机 nonce。
  • 签名由本地钱包生成,私钥从不出机器。
  • 这套 EIP-3009 结构定义在 packages/core/src/x402.ts,签名构造见 packages/core/src/x402.ts。

🔒 好处:金额被签名锁死、有效期很短、nonce 防重放,即使签名被截获也难以滥用。

第 4 步:携带签名重试,USDC 直达服务商

客户端把签名后的支付信息放进 PAYMENT-SIGNATURE 头,重试原请求。校验方结算 USDC 后返回 200 和 payment-response 结算回执。整个支付执行与结算判定在 packages/core/src/x402-pay.ts。

步骤 发生什么 关键产物
1 请求 API 被拦截 HTTP 402 + 报价挑战
2 解析报价 锁定 Base / USDC / 金额 / payTo
3 本地签名 EIP-3009 授权签名
4 带签名重试 200 + 结算回执

每次支付都会通过 builder-code 扩展标识客户端为 vapi,方便服务商与统计溯源,见 packages/core/src/x402.ts。

vAPI Network:开箱即用的非托管 x402 客户端

vAPI Network(vapi-network)是上述协议的一个开源、非托管 TypeScript 客户端。它的定位是"一个钱包,调用所有 x402 API",可以从终端、MCP 客户端或你自己的代码里发起支付。

vAPI Network 桌面端图标——一个基于 x402 协议、用 USDC 在 Base 上为 API 调用按次付费的开源非托管客户端

它的几个关键特性:

  • 非托管:私钥加密存在本机(~/.vapi/vault.json),由操作系统密钥库(macOS Keychain / Windows DPAPI / Linux libsecret)保存的设备密钥解锁,可选密码二次保护。
  • 直付服务商:USDC 直接付给 API 提供方,vAPI Call 不收手续费。
  • 本地回执:每次付费调用都写入本地只增账本,记录报价、结算与延迟。
  • 签名前拦截:在执行签名前先套用消费策略,超限直接拒绝。

更多钱包与托管模型说明见 docs/wallets.md,支付与回执细节见 docs/call.md。

安全护栏:消费上限与本地保险库

让 AI 自动花钱,最怕"失控"。vAPI 用两层护栏保证安全:

1. 消费上限(Spend Caps)——在签名之前就拦截,分三类:

上限 含义 如何调整
per_call 单次调用最高金额 vapi accounts caps <name> --per-call <usd>
per_day 当日累计最高金额 vapi accounts caps <name> --per-day <usd>
max_price 本次支付的价格上限 vapi pay <ref> --max <usd>

一旦超限,会抛出 spend_cap_exceeded 错误并什么都不签,同时给出可直接复制的提额命令。消费账本与上限逻辑在 packages/core/src/spend-policy.ts。

2. 本地保险库(Vault)+ 资金天花板——每个账户默认有 5 USDC 的 Base 资金天花板,超额部分会自动扫回主人钱包,"丢一台设备"最多损失一点工作余额,核心资产始终在主人手里。详见 docs/wallets.md。

3 分钟上手:安装并支付第一次 API 调用

在终端里,几条命令就能跑通完整链路:

# 安装
npm i -g vapi-network

# 初始化设备保险库并创建默认账户(可安全重复执行)
vapi setup

# 打开托管充值页,为你的地址准备 USDC
vapi fund

# 搜索付费 API(合并多个目录,带来源与健康度)
vapi search "weather"

# 付费调用:--max 0.02 表示最高付 0.02 美元
vapi pay <listing-ref> --max 0.02

# 查看本地回执账本:每笔调用的报价、结算、延迟
vapi receipts

⚠️ 恢复短语只在真实终端打印,vAPI 无法替你找回;建议开启加密云备份 vapi backup --cloud,且只有主人能批准恢复。

三种入口:CLI、MCP 与 SDK

同一套底层能力,面向三类用户:

  • CLI(终端):适合脚本与人工操作,即上面的 vapi 命令。
  • MCP(Agent):把支付能力注册成 MCP 工具,让 Claude Code、Cursor 等 Agent 直接调用 call.search / call.inspect / call.pay。给 Agent 一个带消费上限的独立账户,它就无法超额花钱。配置见 docs/mcp.md。
  • SDK(代码):createVapiClient 把 docs、Call、Router、本地 Agent 装进一个 API,方便集成到自己的应用。用法见 docs/sdk.md。

常见问题 FAQ

x402 和普通 API key 订阅有什么区别? x402 是按次即时计费,无需预充值或人工开通;用多少付多少,机器全自动完成,特别适合 AI Agent。

为什么选 USDC 和 Base? USDC 是锚定美元的稳定币,价格几乎不波动,适合精确计价;Base 是低费用、高吞吐的 EVM 链,让几分钱的小额 API 支付在经济上可行。

钱会不会经过 vAPI 抽成? 不会。USDC 直接打到 API 提供方的 payTo 地址,vAPI Call 不收取任何费用。

签名会不会泄露我的私钥? 不会。客户端只对"授权转账"做签名,私钥保存在本机保险库,从不离开你的设备。

小结

  • x402 协议用 HTTP 402 + 标准 JSON 报价,让 API 能"即付即用",天然适配 AI Agent。
  • 支付走 EIP-3009 授权签名,金额锁死、有效期短、私钥不出机器,安全可控。
  • vAPI Network 提供非托管钱包、消费上限、本地回执,让"用 USDC 在 Base 上按次付费"在终端、MCP、SDK 里都能开箱即用。

想深入细节,可从项目说明 README.md 入手,再按 docs/call.md、docs/wallets.md 与 docs/mcp.md 分主题查阅。

登录后查看全文
vapi-network