X402

X402 让您通过钱包认证并维护预付的 USDC 余额来使用 Venice 的付费 API 路由。无需 API 密钥或账户。签署一条消息、在 Base 或 Solana 上充值，即可调用任何支持的路由。

钱包认证

在 X-Sign-In-With-X 头中使用已签名的 Sign-In-With-X 负载进行身份验证。

使用 USDC 付款

使用 Base 或 Solana 上的 USDC 维护可消费余额。

DIEM 优先

如果钱包链接到有 DIEM 余额的 Venice 账户，会优先消费 DIEM。

什么是 X402？

X402 是一个开放的支付标准，让应用程序和 agent 可以使用加密货币以编程方式支付服务。Venice 实现了 X402，使钱包可以在 Base 或 Solana 上直接使用 USDC 进行推理认证和支付。

前置条件

在 Base 或 Solana 上的钱包
所选链的 gas 原生代币，例如 Base 上的 ETH 或 Solana 上的 SOL
所选链上的 USDC（或来自已链接 Venice 账户的现有 DIEM 支持余额）

考虑为自动化使用专用钱包，而不是您的主资金钱包。

快速开始

venice-x402-client SDK 提供了钱包认证、充值和余额跟踪的辅助函数。

npm install venice-x402-client

import { VeniceClient } from 'venice-x402-client'

const venice = new VeniceClient(process.env.WALLET_KEY)

await venice.topUp(10) // skip if the wallet already has spendable balance

const response = await venice.chat({
  model: 'kimi-k2-5',
  messages: [{ role: 'user', content: 'Hello!' }]
})

客户端为每个请求生成新的 X-Sign-In-With-X 头，并自动从 X-Balance-Remaining 响应头跟踪余额。

与 OpenAI 兼容工具配合使用

如果您使用接受自定义 fetch 的工具，使用 createAuthFetch 为任何请求添加钱包认证：

import { createAuthFetch } from 'venice-x402-client'

const authFetch = createAuthFetch(process.env.WALLET_KEY)

可用辅助函数

SDK 包括最常见 Venice x402 路由的一流辅助函数。对于未覆盖的内容，直接使用 request() 或 createAuthFetch()。

类别	方法
Chat	`chat()`、`chatStream()`
Responses	`responses.create()`、`responses.stream()`
Images	`images.generate()`、`images.generations()`、`images.upscale()`、`images.edit()`、`images.multiEdit()`、`images.backgroundRemove()`
Audio	`audio.speech()`、`audio.transcribe()`、`audio.queue()`、`audio.retrieve()`、`audio.complete()`
Video	`video.queue()`、`video.retrieve()`、`video.generate()`、`video.complete()`、`video.transcribe()`
Embeddings	`embeddings()`
Models	`models()`
Wallet	`getBalance()`、`getTransactions()`、`topUp()`

手动流程

如果您不使用 SDK 或需要了解底层协议，下面是逐步流程。对于新钱包，假设您需要先充值，除非它已经有可消费的 DIEM 余额。 Venice 期望一个 Base64 编码的 JSON 负载，包含已签名的 Sign-In-With-X 消息。EVM 钱包在 Base 上签署 EIP-4361 SIWE 消息。Solana 钱包使用 Ed25519 签署 Solana SIWX 消息。为每个请求流程生成新的 nonce 和时间戳。对于 Solana，将 chainId 设置为 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp，在编码的 JSON 负载中包含 type: "ed25519"，并以 base58 或 base64 提供 Ed25519 签名。已签名消息以 <domain> wants you to sign in with your Solana account: 开头，后跟钱包地址和标准 URI、Version、Chain ID、Nonce、Issued At 和可选的 Expiration Time 字段。

import { Wallet } from 'ethers'
import { SiweMessage, generateNonce } from 'siwe'

const wallet = new Wallet(process.env.EVM_PRIVATE_KEY)
const now = new Date()
const resourceUrl = 'https://api.venice.ai/api/v1/chat/completions'

const siwe = new SiweMessage({
  domain: 'api.venice.ai',
  address: wallet.address,
  statement: 'Sign in to Venice AI',
  uri: resourceUrl,
  version: '1',
  chainId: 8453,
  nonce: generateNonce(),
  issuedAt: now.toISOString(),
  expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
})

const message = siwe.prepareMessage()
const signature = await wallet.signMessage(message)

const xSignInWithX = Buffer.from(
  JSON.stringify({
    address: wallet.address,
    message,
    signature,
    timestamp: now.getTime(),
    chainId: 8453,
  }),
  'utf8',
).toString('base64')

console.log(xSignInWithX)

步骤 2：检查余额

在发出付费请求之前，验证钱包是否有可消费余额：

export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request GET \
  --url "https://api.venice.ai/api/v1/x402/balance/$WALLET_ADDRESS" \
  --header "X-Sign-In-With-X: $X402_AUTH"

响应包括：

canConsume：钱包是否可以发出付费请求
balanceUsd：当前可消费余额
minimumTopUpUsd 和 suggestedTopUpUsd：充值指引
diemBalanceUsd：DIEM 支持余额（如有）

walletAddress 路径参数接受 EVM 地址（0x...）或 Solana base58 地址。

步骤 3：充值

使用 Base 或 Solana 上的 USDC 充值：

curl --request POST \
  --url https://api.venice.ai/api/v1/x402/top-up

首次调用返回 402 Payment Required，带有包含 accepts 数组的 PAYMENT-REQUIRED 头。每个条目描述一个接受的支付选项，包括 network、asset、payTo 和 amount。选择您要支付的 Base 或 Solana 选项，使用这些精确详情构建 X-402-Payment 头，并重试相同的路由。

为 Base 构建 X-402-Payment 头

以下脚本在 Base 上创建已签名的 x402 支付并发送充值请求。需要 x402 和 viem npm 包。

export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

export X402_PAYMENT="$(
node --input-type=module <<'EOF'
import { createPaymentHeader } from "x402/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const amountUsd = 5;
const amountBaseUnits = String(Math.round(amountUsd * 1e6));

const header = await createPaymentHeader(signer, 2, {
  scheme: "exact",
  network: "base",
  maxAmountRequired: amountBaseUnits,
  resource: "https://api.venice.ai/api/v1/x402/top-up",
  description: "Venice x402 top-up",
  mimeType: "application/json",
  payTo: "0x2670B922ef37C7Df47158725C0CC407b5382293F",
  maxTimeoutSeconds: 300,
  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  extra: { name: "USD Coin", version: "2" },
});

process.stdout.write(header);
EOF
)"

curl -X POST "https://api.venice.ai/api/v1/x402/top-up" \
  -H "X-402-Payment: $X402_PAYMENT"

在生产环境中，使用最新的 PAYMENT-REQUIRED / accepts 响应作为权威来源，而不是硬编码这些值。对于 Solana 充值，从 accepts 中返回的 Solana 条目构建支付。Solana 条目使用 network: "solana"、USDC mint 作为 asset，并可能包括网络特定元数据，如 extra.feePayer。

步骤 4：发出请求

一旦钱包有可消费余额，使用 X-Sign-In-With-X 头调用任何支持的端点：

export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request POST \
  --url https://api.venice.ai/api/v1/chat/completions \
  --header "Content-Type: application/json" \
  --header "X-Sign-In-With-X: $X402_AUTH" \
  --data '{
    "model": "kimi-k2-5",
    "messages": [
      {
        "role": "user",
        "content": "Hello from an x402-authenticated wallet."
      }
    ]
  }'

成功响应可能包含 X-Balance-Remaining 头。

步骤 5：检查交易（可选）

查看钱包的交易历史：

export WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_OR_SOLANA_ADDRESS
export X402_AUTH=YOUR_BASE64_SIWX_HEADER

curl --request GET \
  --url "https://api.venice.ai/api/v1/x402/transactions/$WALLET_ADDRESS?limit=10&offset=0" \
  --header "X-Sign-In-With-X: $X402_AUTH"

账本包括 TOP_UP、CHARGE 和 REFUND 等条目。 walletAddress 路径参数接受 EVM 地址（0x...）或 Solana base58 地址。

支持的路由

付费推理路由

以下公开付费 Venice 路由当前支持 x402 钱包认证。

类别	端点
Chat	`POST /api/v1/chat/completions`、`POST /api/v1/responses`
Image	`POST /api/v1/image/generate`、`POST /api/v1/images/generations`、`POST /api/v1/image/upscale`、`POST /api/v1/image/edit`、`POST /api/v1/image/multi-edit`、`POST /api/v1/image/background-remove`
Embeddings	`POST /api/v1/embeddings`
Audio	`POST /api/v1/audio/speech`、`POST /api/v1/audio/transcriptions`、`POST /api/v1/audio/complete`、`POST /api/v1/audio/queue`、`POST /api/v1/audio/retrieve`
Video	`POST /api/v1/video/complete`、`POST /api/v1/video/queue`、`POST /api/v1/video/retrieve`、`POST /api/v1/video/transcriptions`

充值路由

端点	认证	用途
`POST /api/v1/x402/top-up`	首次请求：无。重试：`X-402-Payment`	使用接受的 Base 或 Solana 支付选项向钱包的可消费余额添加 USDC credit

仅钱包路由

这些路由使用 X-Sign-In-With-X 进行身份识别，但不收取余额。

端点	用途
`GET /api/v1/x402/balance/{walletAddress}`	检查 EVM 或 Solana 钱包地址的可消费余额
`GET /api/v1/x402/transactions/{walletAddress}`	查看 EVM 或 Solana 钱包地址的交易历史

错误

状态	可能原因	应对方式
`401`	Sign-In-With-X 负载格式错误或已过期	使用新的 nonce 和时间戳重建 `X-Sign-In-With-X`
付费路由上 `402`	可消费余额不足	充值并重试
`/x402/top-up` 上 `402`	预期。这是支付发起流程。	使用返回的支付详情构建 `X-402-Payment` 并重试
余额或交易上 `403`	钱包不匹配	确保已认证钱包与 `walletAddress` 路径参数匹配
充值上 `400`	支付头格式错误	从最新的 `402` 响应重建

对于 agent

流程相同。将私钥存储在环境变量或机密管理器中，并在请求之前检查余额，以避免不必要的 402 往返。

x402 客户端 SDK

官方 Venice x402 Node.js/TypeScript 客户端。

API 定价

查看模型定价以及 Venice 如何收取使用费用。

Chat Completions

用于基于钱包访问的常见付费路由。

API 规范

参考文档和原始规范访问。

钱包认证

使用 USDC 付款

DIEM 优先

​什么是 X402？

​前置条件

​快速开始

​与 OpenAI 兼容工具配合使用

​可用辅助函数

​手动流程

​步骤 1：创建 X-Sign-In-With-X 头

​步骤 2：检查余额

​步骤 3：充值

​为 Base 构建 X-402-Payment 头

​步骤 4：发出请求

​步骤 5：检查交易（可选）

​支持的路由

​付费推理路由

​充值路由

​仅钱包路由

​错误

​对于 agent

​相关资源

x402 客户端 SDK

API 定价

Chat Completions

API 规范

什么是 X402？

前置条件

快速开始

与 OpenAI 兼容工具配合使用

可用辅助函数

手动流程

步骤 1：创建 X-Sign-In-With-X 头

步骤 2：检查余额

步骤 3：充值

为 Base 构建 X-402-Payment 头

步骤 4：发出请求

步骤 5：检查交易（可选）

支持的路由

付费推理路由

充值路由

仅钱包路由

错误

对于 agent

相关资源