vAPI Network SDK 开发者指南:用 createVapiClient 在 TypeScript 项目集成按次付费 API

原创2026-11-06 18:34:391,648 阅读

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。

vAPI Network SDK 图标:面向开发者的 x402 按次付费 API 支付客户端

二、快速安装与初始化: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 步

  1. npm i vapi-network 安装(Node.js ≥ 22);
  2. vapi setup + vapi fund 建钱包、充 USDC;
  3. createVapiClient({ account }) 创建钱包绑定客户端;
  4. vapi.call.search → inspect → pay 完成按次付费调用,始终传 maxPriceUsd 防止报价漂移;
  5. 用 SpendCapExceededError 与 vapi pay --resume 处理限额拦截与结算确认。

从此你的 TypeScript 项目不再需要为每个数据源申请 API Key——一个本地钱包,就能按次付费调用所有 x402 API。

登录后查看全文
vapi-network