vAPI Network SDK 开发者指南:用 createVapiClient 在 TypeScript 项目集成按次付费 API
vAPI Network SDK 开发者指南:用 createVapiClient 在 TypeScript 项目集成按次付费 API
vAPI Network 是一款开源、非托管的 TypeScript 客户端,让你用一个本地钱包发现并支付所有 x402 API——用 Base 链上的 USDC 按次付费,无需注册账号、无需 API Key。它的核心 SDK 入口是 createVapiClient:几行代码即可在 TypeScript 项目中搜索、检查并支付按次付费 API,同时支持 vAPI Router 模型调用和本地 Agent 运行,且每笔支出都受你本地的消费限额(spend caps)保护,vAPI 自身不收取任何手续费。
一、vAPI Network 是什么:一个钱包调用所有 x402 API
🔑 x402 是一种基于 HTTP 402 状态码的 API 支付协议:API 服务先返回 402「Payment Required」报价,客户端用 USDC 完成链上签名支付后,再携带支付凭证重新请求,服务方验证后直接返回数据。
vAPI Network 为这个流程提供了完整的买方控制(buyer-controlled)方案:
| 特性 | 说明 |
|---|---|
| 🔐 非托管 | 私钥只存在于你本机,由操作系统密钥库(Keychain/DPAPI/libsecret)加密保管 |
| 💸 按次付费 | 每次 API 调用独立报价、独立支付,USDC 在 Base(或 Arc)链上结算 |
| 🛡️ 消费限额 | 单次/每日/最高价等多层 spend caps,超额在签名前直接拦截 |
| 🧾 本地收据 | 每次支付写入本机追加式账本 receipts.jsonl,含报价、结算状态与延迟 |
| 🚫 零抽成 | vAPI Call 不收费,服务费直接支付给提供方 |
本地状态默认存放在 ~/.vapi/,包括配置、设备金库(device vault)、账户与收据,详见 docs/configuration.md。
二、快速安装与初始化:3 条命令跑通环境
要求 Node.js ≥ 22,安装只需一条命令:
npm i vapi-network
vapi-network 是零运行时依赖的打包发行版(bundled),同时提供 CLI 与 SDK。首次使用前需要创建并充值本地钱包:
vapi setup # 创建设备金库并派生默认账户 main(可安全重跑)
vapi fund # 打开托管充值页,向你的地址充入 Base 链 USDC
vapi balance # 确认余额
💡 提示:新账户默认限额为 单次 $0.10 / 每日 $1.00,可用
vapi accounts caps <name> --per-call 0.5 --per-day 5自行调高。恢复短语只在终端展示,vAPI 无法替你找回,请妥善保存。
三、createVapiClient 完整用法:四组 API 一个钱包
安装后,一行代码即可创建客户端(完整实现见 packages/vapi-network/src/client.ts#L114):
import { createVapiClient } from "vapi-network";
const vapi = await createVapiClient({ account: "main" });
// 1. 搜索 x402 API 并按次付费
const listings = await vapi.call.search("Base DEX volume");
const result = await vapi.call.pay({ id: "base-dex-volume", maxPriceUsd: 0.05 });
console.log(result.body);
// 2. 通过 vAPI Router 调用大模型
const reply = await vapi.router.chat({
model: "venice/claude-sonnet-5",
messages: [{ role: "user", content: "Summarise Base DEX activity." }],
});
// 3. 充值 Router 余额($1/$5/$20/$50 档位)
const purchase = await vapi.router.buy(5);
console.log(purchase.balance);
四组命名空间一览
客户端返回的 VapiClient 类型定义在 packages/vapi-network/src/client.ts#L78-L111:
| 命名空间 | 主要方法 | 用途 |
|---|---|---|
vapi.call |
search / inspect / pay |
发现、检查、支付 x402 API |
vapi.router |
models / usage / chat / buy / openai |
托管模型推理;openai() 返回 OpenAI 兼容的 baseURL + key,可直接接入任意框架 |
vapi.agent |
run(profileName, task) |
运行一个带独立钱包和限额的本地 Agent |
vapi.docs |
search / read / ask |
查询官方文档助手,无需钱包 |
常用配置项
createVapiClient 的参数类型 VapiClientOptions(packages/vapi-network/src/client.ts#L62-L76):
| 参数 | 作用 |
|---|---|
account |
账户名;缺省时回退到环境变量 VAPI_WALLET,再到机器默认账户 |
home |
本地状态目录;缺省为 VAPI_HOME 或 ~/.vapi |
passphrase |
仅在无账户、无 VAPI_KEYSTORE_PASSWORD 且系统密钥库无记录时使用 |
fetch |
可注入自定义 fetch(测试或内嵌运行时) |
⚠️ 注意:
{ wallet }是{ account }的废弃别名,仍可使用但会向 stderr 打印一行弃用警告。
零配置起步:docs 命名空间无需任何初始化
即使还没运行 vapi setup,createVapiClient() 也会返回一个「仅文档」客户端,docs 三件套直接可用:
const vapi = await createVapiClient();
const matches = await vapi.docs.search("spend caps", { limit: 5 });
const answer = await vapi.docs.ask("How do agent spend caps work?");
这是集成 SDK 时的理想冒烟测试:不触碰钱包、不产生任何支付。
四、消费限额:理解 SpendCapExceededError 拦截机制
安全是这套 SDK 的默认行为——限额检查发生在签名之前,被拦截的调用不会生成任何支付授权,也不会扣款。
当限额阻止支付时,SDK 抛出 SpendCapExceededError(错误码 spend_cap_exceeded,retryable: false),携带字段:cap、amountUsd、limitUsd、可选的 spentUsd 与 wallet,以及 command(告诉你该执行哪条命令来调整限额)。
cap 值 |
含义 | 如何解除 |
|---|---|---|
per_call |
本次报价超过单次限额 | 终端执行返回的 vapi accounts caps 命令 |
per_day |
今日(UTC)累计支出将超过每日限额 | 同上,调高 --per-day |
max_price |
报价高于你传入的 maxPriceUsd |
确认新价格合理后调大参数 |
max_amount |
报价超过 SDK 的 maxAtomic(USDC 原子单位) |
调大支付参数;此时 command 为 null |
run_budget |
超出 Agent/Swarm 本次运行预算 | 调大运行预算 |
在代码中的标准处理方式——从 vapi-network 的 core 命名空间捕获该错误类:
import { createVapiClient, core } from "vapi-network";
try {
await vapi.call.pay({ id: "weather", maxPriceUsd: 0.05 });
} catch (error) {
if (!(error instanceof core.SpendCapExceededError)) throw error;
console.error(error.cap, error.amountUsd, error.limitUsd, error.command);
}
限额调整只能由用户在终端完成(vapi accounts caps <name> --per-call <usd> --per-day <usd>),SDK 代码无法自行提额——这正是买方控制的设计意图。
五、支付结果、收据与失败恢复
每次 vapi.call.pay 成功都会:① 返回服务方的响应(body)与支付凭证(payment,含网络、金额、收款方与结算证明);② 写入本机追加式收据账本。
遇到网络抖动导致支付结果不明(settlement_unknown)时,切勿直接重付。正确姿势是先查结算状态:
vapi pay --resume <receipt-id>
| 状态 | 含义 | 动作 |
|---|---|---|
Settled |
支付已成功 | 不要重复支付 |
Expired |
授权从未使用且已过期 | 可以安全重付 |
Pending |
未使用但仍有效 | 等待其打印的时间点 |
日常运维建议:
vapi receipts --account main # 每次付费调用的报价、结算与延迟
vapi stats --range 7d # 支出、结果分布与延迟百分位
完整的错误恢复对照表(400/422 输入不匹配、429 限流、unsupported_network 等)见 docs/call.md。
六、进阶:给 Agent 配一个限额钱包
如果要在项目里跑本地 Agent,推荐为它单独派生账户,让它与主账户的限额互不影响:
vapi accounts add researcher # 派生新账户并链接
vapi accounts caps researcher --per-call 0.02 --per-day 0.5
vapi fund --account researcher # 给它充一笔小额 USDC
// 用独立账户运行 Agent 任务
const vapi = await createVapiClient({ account: "researcher" });
const run = await vapi.agent.run("researcher", "Summarise today's Base DEX volume");
服务端/CI 场景下,可用 vapi vault protect + VAPI_VAULT_PASSWORD 管理受保护金库的解锁会话(8 小时有效),详见 docs/wallets.md。
七、关键源码与文档地图
| 资源 | 路径 |
|---|---|
| SDK 完整文档 | docs/sdk.md |
| 按次付费 API 指南(Call) | docs/call.md |
客户端入口与 createVapiClient |
packages/vapi-network/src/client.ts |
包导出(createVapiClient、core、mcp、sources) |
packages/vapi-network/src/index.ts |
| Agent 技能说明 | packages/vapi-network/SKILL.md |
| 可运行示例:搜索并支付一个 x402 API | examples/pay-with-sdk.ts |
| 可运行示例:钱包列表、创建与限额管理 | examples/wallets.ts |
| 网络、充值与环境变量配置 | docs/configuration.md |
| Router 与 Compute 指南 | docs/router.md |
八、总结:从集成到生产只需 5 步
npm i vapi-network安装(Node.js ≥ 22);vapi setup+vapi fund建钱包、充 USDC;createVapiClient({ account })创建钱包绑定客户端;vapi.call.search→inspect→pay完成按次付费调用,始终传maxPriceUsd防止报价漂移;- 用
SpendCapExceededError与vapi pay --resume处理限额拦截与结算确认。
从此你的 TypeScript 项目不再需要为每个数据源申请 API Key——一个本地钱包,就能按次付费调用所有 x402 API。