技能介绍

要解决的问题

调用 Venice 推理接口时，钱包余额不足会得到一个 402 响应。响应里带结构化的充值说明和 SIWE 挑战，但除非你手动签名交易、等待确认、重试请求，否则调用不会成功。没有账户、没有 API key，按请求付费，怎么让这个流程自动化？

技能如何工作

x402 是 Venice 的钱包支付协议：USDC on Base 结算。它暴露三个管理端点和一个协议层响应：

POST /x402/top-up — 先不带 header 发现支付要求，再用 X-402-Payment 签名完成结算
GET /x402/balance/{walletAddress} — 查询钱包 USDC 余额，需要 SIWE
GET /x402/transactions/{walletAddress} — 分页账本，类型有 TOP_UP、CHARGE、REFUND

端到端流程四步：调用推理 → 收到 402（含 topUpInstructions 和 siwxChallenge）→ 调用 /x402/top-up 发现要求 → 用 x402 SDK 做 EIP-712 transferWithAuthorization 签名并重试。venice-x402-client SDK 把这四步包在一起：捕获 402、自动充值到设定金额、重试。

容易踩的坑

PAYMENT-REQUIRED（全大写连字符）是 header，内含 base64 编码的 x402 paymentRequired 对象；402 body 是更丰富的余额/充值文档，两者不是一回事。
accepts[].amount 已经是 base units（比如 "5000000" = 5 USDC），不要再次乘 decimals。
balanceUsd 只是 USDC credit；diemBalanceUsd 是另一个关联账户数字，需要自己加总。
SIWE signer 必须和 path 上的 walletAddress 一致，否则 403。
缺少 SIWE header 返回 402；header 存在但无效才返回 401。

适用边界

用 x402 SDK 包做签名，别手写 EIP-712：nonce 复用会导致 INVALID_PAYMENT。
最低充值金额默认 $5，但部分 allow-listed 钱包有更低的 per-wallet override，应读取 topUpInstructions 或 /x402/balance 返回的 minimumTopUpUsd，不要硬编码。
DIEM、BUNDLED_CREDITS、Bearer-account USD 与钱包 credit 是独立体系，查账户余额用 venice-billing。

截图预览

使用场景

调用 /chat/completions 时钱包余额不足收到 402，需要按 topUpInstructions 用 x402 SDK 签名 USDC 转账并自动重试的 Agent 后端。
对账场景下需要查询某钱包地址的 USDC 余额与分页交易流水（TOP_UP/CHARGE/REFUND），核对扣费记录对应的 requestId 与 modelId。
搭建无账户按请求付费的推理调用流程，不想维护 API key 或订阅计划，用钱包 credit 按次结算的独立开发者。
实现 SIWE 鉴权时需要处理「缺 header 返回 402、header 无效返回 401、signer 与 path 钱包不符返回 403」多种分支的后端工程师。

适合人员

负责 Agent 调用链的后端工程师，想让推理请求在钱包余额不足时自动充值并重试。
搭建无账户 pay-per-request 推理服务的开发者，需要用 USDC on Base 处理按请求扣费。
维护钱包账本与对账系统的工程师，需要查询 /x402/balance 和 /x402/transactions 核对 TOP_UP/CHARGE/REFUND。
实现 SIWE 鉴权中间件的开发者，要区分 402（缺 header）与 401（header 无效）并处理钱包地址匹配。