前言¶

讓 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