一文读懂 x402 协议:vAPI Network 如何用 USDC 在 Base 上为 API 调用按次付费
一文读懂 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 分主题查阅。