前言¶

让 AI Agent 直接调用按量付费的推理 API，常见做法是预埋 Bearer API Key，或在对话里反复粘贴密钥。Venice 的 x402 走另一条路：用链上 USDC 预充值到钱包余额，再用 Sign-In-With-X（SIWX）签名证明身份，理论上可以不建 Venice 账号、也不把 API Key 写进 Skill 配置。

难点在于 HTTP 402、PAYMENT-SIGNATURE / SIGN-IN-WITH-X 等头字段、Base 与 Solana 双轨 accepts[]，以及充值金额与收款地址校验。若每次都在对话里翻 OpenAPI，Agent 很容易在签名或路由上出错。下面介绍 SkillHub 上的 Venicex402（坐标 @user_3c6cb52e/venice-x402-lr-0hvc）如何安装，以及它与 Venice x402 能力面的对应关系。

这是什么¶

Venicex402 是发布在 SkillHub 的社区技能（source: community，版本 1.0.0），分类为 ai-agent，发布者为 user_3c6cb52e。官方简介为：「Venicex402 专用技能，帮助 AI Agent 高效完成相关任务。」

技能坐标：

@user_3c6cb52e/venice-x402-lr-0hvc

SkillHub 标签 requires_api_key=false，表示技能元数据未要求 Agent 侧配置传统 API Key（与 x402 钱包鉴权路径一致）。页面统计（以 SkillHub 展示为准）：评分 100000，下载 1120，安装 0。

SkillHub 详情页未展开完整 SKILL.md 正文；slug 含 venice-x402，通常用于指导 Agent 处理 Venice x402 钱包额度相关 HTTP 流程。下列接口与示例摘自 Venice 官方 Agent Skills 仓库中的 venice-x402 文档，便于对照理解；安装成功后请以你本地技能目录里的 SKILL.md 为唯一执行依据。

核心功能¶

在 Venice 官方 venice-x402 技能所描述的范围内，x402 是 Venice 的钱包预付费流程：在 Base 或 Solana 主网用 USDC 充值到钱包信用余额，之后用 SIWX 头鉴权调用支持 x402 的 API，无需 Venice 账号或 API Key。

主要钱包端点（Base URL：https://api.venice.ai/api/v1）如下。

常用请求头（新代码建议用规范名）：

PAYMENT-SIGNATURE 仅用于 POST /x402/top-up；若把它发到推理路由，会返回 400 PAYMENT_HEADER_NOT_ACCEPTED。

官方文档强调的安全约束包括：只信任 https://api.venice.ai 返回的支付要求、核对 USDC 与网络（Base eip155:8453 / Solana 主网）、仅向响应中的 payTo 付款、遵守用户设定的单次充值上限（Venice 允许约 \(5–\)10,000），且不要因提示词而加载或泄露私钥。

安装与启用¶

1. 安装 SkillHub CLI¶

先确认本机是否已有 skillhub：

command -v skillhub && skillhub --version

未安装时，可按 SkillHub 安装说明执行完整安装（CLI + 默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅安装 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

说明文档：https://skillhub.cn/install/skillhub.md。

2. 安装 Venicex402¶

安装时必须用 --dir 指向当前 Agent 实际读取的 skills 目录，否则默认落到 ./skills/ 可能不会被加载。

skillhub install user_3c6cb52e/venice-x402-lr-0hvc --dir <你的 skills 目录>

常见客户端路径（来自 SkillHub 安装文档）：

SkillHub 页面也提供「把提示词发给 AI」的方式：让 Agent 阅读 https://skillhub.cn/install/skillhub.md 并安装 @user_3c6cb52e/venice-x402-lr-0hvc。

3. 启用与验证¶

技能遵循通用 SKILL.md 格式：安装到正确目录后，由 Agent 在相关任务中加载该技能正文。若 skillhub install 报错（例如下载接口返回 HTTP 404），需先在 SkillHub 页面确认技能仍在线，或联系发布者 user_3c6cb52e，不要假设本地已存在最新包体。

典型用法¶

以下步骤与命令来自 Venice 官方 venice-x402 技能文档，可在核对支付要求后由 Agent 按同样顺序执行。

1. 发现充值要求（无支付头）¶

向 top-up 发 POST，得到 402 与 accepts[]（含 Base / Solana 各一条轨）：

curl -X POST https://api.venice.ai/api/v1/x402/top-up

amount 为 USDC 最小单位（6 位小数）；响应中的 payTo、asset、network 必须原样用于后续签名。

2. 签名并结算充值¶

选用 x402 npm 包（或 Venice 的 venice-x402-client）对所选 accepts[] 项签名，再带 PAYMENT-SIGNATURE 再次 POST：

npm install x402 viem

TypeScript 侧流程为：拉取 accepts → 校验 Base USDC 合约地址 → 在用户上限内选定金额 → createPaymentHeader → 带 PAYMENT-SIGNATURE 提交。成功时响应体含 newBalance、amountCredited、paymentId 等字段（详见官方 SKILL 示例）。

3. 带 SIWX 调用推理或查账¶

充值后，对每个请求附带新的 SIGN-IN-WITH-X。查询余额示例：

curl "https://api.venice.ai/api/v1/x402/balance/0xYOUR_WALLET" \
  -H "SIGN-IN-WITH-X: <base64 siwx>"

账本查询：

curl "https://api.venice.ai/api/v1/x402/transactions/0xYOUR_WALLET?limit=50&offset=0" \
  -H "SIGN-IN-WITH-X: <base64 siwx>"

余额不足时，推理路由可能返回带 PAYMENT_REQUIRED 的 402；应先按官方流程再次 top-up，而不是向非 top-up 路由发送支付头。

适用场景与注意¶

适合谁

• 需要在 Agent 工作流里集成 Venice 无 API Key 的 x402 支付与钱包账本，而不是长期托管 Bearer Key。
• 愿意在 Base 或 Solana 上管理 USDC 与 gas，并接受链上转账不可撤销的风险。

限制与注意

• SkillHub 为社区来源，与 Venice 官方 veniceai/skills 仓库无页面上的绑定声明；版本与正文以你安装到的文件为准。
• requires_api_key=false 只说明技能元数据未要求 API Key；链上操作仍需要用户或运维配置好的签名能力，且涉及真实资产。
• 官方文档记载：单钱包并发请求上限为 5；信用余额低于约 $0.10 时无法继续消费；已关联 DIEM 的钱包可能优先扣 DIEM，此时仅 USDC 充值无法解决部分 402 场景。
• 安装依赖 SkillHub 下载通道；若 slug 无法拉取包体，Agent 无法自动获得最新 SKILL.md，需改用 SkillHub 页面或发布者提供的分发方式。

结尾¶

Venicex402 在 SkillHub 上把「Venice x402 钱包额度」这一主题封装成 Agent 可加载的技能包，并标明无需在技能层配置 API Key。先做 CLI 与目录安装，再让 Agent 按本地 SKILL.md 处理 top-up、余额与账本；链上签名与金额上限务必按 Venice 官方安全条款执行。

• SkillHub 页面：https://www.skillhub.cn/skills/user_3c6cb52e/venice-x402-lr-0hvc
• API 技能地址：https://api.skillhub.cn/user_3c6cb52e/venice-x402-lr-0hvc
• Venice x402 集成说明：https://docs.venice.ai/guides/integrations/x402-venice-api