Venice 鉴权

调用 Venice API 时，开发者常面临一个基础但棘手的抉择：如何为服务端服务和无账户的链上代理选择合适的鉴权方式。@user_3c6cb52e/venice-auth-xenh 这一技能正是为了厘清 Venice 提供的两套并列鉴权机制：Bearer API Key 与 x402 钱包（SIWE）签名。它不提供空洞的框架，而是直接给出两种方案在架构选型、字段规范与错误排查上的工程细节。

核心能力与鉴权逻辑

1. Bearer API Key（服务端方案）
当宿主环境拥有 Venice 账户，且需要统一的用量分析（/billing/usage-analytics）或精细化的密钥管理时，应选择 Bearer 方案。API Key 支持设置 consumptionLimits（USD 和/或 DIEM 上限）与 apiKeyType。密钥类型决定了可用的接口范围——只有 ADMIN 类型的密钥才能管理其他子密钥。计费系统会按 DIEM 质押、USD 余额及捆绑积分的顺序自动扣费。

2. x402 钱包签名（无账户方案）
对于需要按次结算、无账户依赖的 AI Agent 或无服务器函数，x402 提供了基于以太坊钱包的鉴权。该方案要求构造符合 EIP-4361 标准的 SIWE 消息，并将其编码后放入 X-Sign-In-With-X 请求头。

在处理 SIWE 签名时，必须严格对齐以下字段约束：

• domain：必须是预定义的 Venice 域名白名单之一（如 api.venice.ai），验证仅针对此字段，而非请求的 Host。
• chainId：固定为 Base 链的 8453，接受数值、数字字符串或 CAIP-2 格式。
• statement：虽然允许任意字符串，但使用 "Sign in to Venice AI" 能保持用户授权逻辑一致。

关键的工程挑战在于时间控制。签名后的头部凭证有效期极短（从 issuedAt 起最多 5 分钟）。Payload 中的 timestamp 必须与 SIWE 的 issuedAt 在 30 秒以内。此外，nonce 为钱包单次使用机制，5.5 分钟内的重放会触发 X402_SIGN_IN_NONCE_REUSED。

适用场景与避坑指南

这套技能非常适合排查 401 Authentication failed。这类错误往往由以下原因导致：密钥过期、SIWE 超时、时间戳漂移、域名不匹配或链 ID 不支持。Server 端会返回具体的错误码（如 X402_SIGN_IN_DOMAIN_MISMATCH），但由于部分错误回退为通用文本，理解字段背后的逻辑比单纯看日志更重要。

安全注意点：

• Bearer 密钥的行为等同于密码，应通过密钥管理系统存储，并在泄露时立即轮换。
• 浏览器端严禁分发原始私钥，应使用 MetaMask 或 WalletConnect 等钱包扩展。
• 签名后的头部凭证应在约 4 分钟内轮换，切勿跨小时或跨机器重用同一个签名。

如果开发者需要实现 Web3 用户与 Venice Pro 功能的桥接，还可以通过 POST /api_keys/generate_web3_key 将链上钱包与链下密钥绑定，实现两种机制的共存。