venice-x402
Manage Venice x402 wallet credits. Covers POST /x402/top-up (payment discovery + signed USDC settlement), GET /x402/balance/{walletAddress}, GET /x402/transactions/{walletAddress}, USDC on Base (chain 8453) and Solana mainnet, the PAYMENT-SIGNATURE / SIGN-IN-WITH-X header names, minimum $5 top-up, transaction types TOP_UP/CHARGE/REFUND, and the x402 v2 PAYMENT-REQUIRED response shape returned by all inference endpoints.
veniceai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add veniceai/skills --skill venice-x402技能说明
name: venice-x402 description: Manage Venice x402 wallet credits. Covers POST /x402/top-up (payment discovery + signed USDC settlement), GET /x402/balance/{walletAddress}, GET /x402/transactions/{walletAddress}, USDC on Base (chain 8453) and Solana mainnet, the PAYMENT-SIGNATURE / SIGN-IN-WITH-X header names, minimum $5 top-up, transaction types TOP_UP/CHARGE/REFUND, and the x402 v2 PAYMENT-REQUIRED response shape returned by all inference endpoints.
Venice x402 (wallet credits)
x402 is Venice's wallet-based payment flow. Pay per request with USDC on Base or Solana mainnet, no account required. Three admin endpoints plus the protocol-level 402 response returned by every inference endpoint.
| Endpoint | Auth | Purpose |
|---|---|---|
POST /x402/top-up | None (discovery) / PAYMENT-SIGNATURE (settlement) | Discover payment requirements, then settle a signed USDC transfer. |
GET /x402/balance/{walletAddress} | SIWX (SIGN-IN-WITH-X) | Current USD balance for a wallet. |
GET /x402/transactions/{walletAddress} | SIWX | Paginated ledger: TOP_UP, CHARGE, REFUND. |
For the SIWX header format itself, see venice-auth.
Header names
Venice accepts three payment header names and two sign-in header names. Send the canonical one in new code; the others exist so older integrations keep working.
| Purpose | Canonical | Also accepted |
|---|---|---|
| Signed payment (settlement) | PAYMENT-SIGNATURE | X-402-Payment (Venice original), X-PAYMENT (x402 v1 / x402-fetch, x402-axios) |
| Wallet sign-in proof | SIGN-IN-WITH-X | X-Sign-In-With-X (Venice original) |
| Payment requirements (response) | PAYMENT-REQUIRED | — |
| Settlement result (response) | PAYMENT-RESPONSE | — |
Pay with a wallet: end-to-end
1. Call an inference endpoint with no balance → 402
Any inference endpoint (e.g. POST /chat/completions) returns a 402 with structured topUpInstructions and siwxChallenge when the wallet balance is too low. The PAYMENT-REQUIRED response header carries the x402 v2 paymentRequired object (base64-encoded JSON containing x402Version, error, resource, accepts[], and optional extensions) — it is not the same payload as the 402 body, which is a richer balance/top-up document.
{
"error": "Payment required",
"code": "PAYMENT_REQUIRED",
"message": "Insufficient x402 balance",
"suggestedTopUpUsd": 10,
"minimumTopUpUsd": 5,
"supportedTokens": ["USDC"],
"supportedChains": ["base", "solana"],
"topUpInstructions": {
"step1": "POST /api/v1/x402/top-up with no payment header to get payment requirements",
"step2": "Choose a payment option from accepts and sign a USDC transfer authorization using the x402 SDK (createPaymentHeader)",
"step3": "POST /api/v1/x402/top-up with the signed X-402-Payment header",
"receiverWallet": "<RECEIVER_WALLET_ADDRESS>",
"tokenAddress": "<USDC_TOKEN_ADDRESS>",
"tokenDecimals": 6,
"network": "eip155:8453",
"minimumAmountUsd": 5
},
"siwxChallenge": {
"info": { "domain": "api.venice.ai", "statement": "Sign in to Venice AI", ... },
"supportedChains": [
{ "chainId": "eip155:8453", "type": "eip191" },
{ "chainId": "eip155:8453", "type": "eip1271" },
{ "chainId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "type": "ed25519" }
]
}
}
topUpInstructions describes the Base rail only (it predates the Solana
rail and still names the EVM receiver, token, and network). It also still names
the legacy X-402-Payment header in step3. To pay on Solana, read the
accepts[] array from POST /x402/top-up instead. siwxChallenge.supportedChains
is the authoritative list of chains and signature types you can sign in with.
2. Discover payment requirements — POST /x402/top-up (no header)
curl -X POST https://api.venice.ai/api/v1/x402/top-up
Response 402. accepts[] carries one entry per payment rail (Base and
Solana today):
{
"x402Version": 2,
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "<USDC_TOKEN_ADDRESS>",
"amount": "5000000", // base units; USDC = 6 decimals → 5 USDC
"payTo": "<RECEIVER_WALLET_ADDRESS>",
"maxTimeoutSeconds": 300,
"extra": { "name": "USD Coin", "version": "2" }
},
{
"scheme": "exact",
"network": "solana",
"asset": "<USDC_MINT_ADDRESS>",
"amount": "5000000",
"payTo": "<SOLANA_RECEIVER_ADDRESS>",
"maxTimeoutSeconds": 300,
"extra": { "name": "USD Coin", "version": "2", "feePayer": "<VENICE_FEE_PAYER>" }
}
]
}
Pick the entry whose network matches your wallet and echo it back unchanged.
Venice accepts either the short alias or the CAIP-2 form on the way in (base
or eip155:8453; solana or solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp), so the
safest thing is to send back exactly what you were given.
On Solana, extra.feePayer is the Venice-operated account that pays the
transaction fee. Set it as the fee payer on the transfer you sign so the payer
does not need SOL.
3. Sign a USDC transfer → POST /x402/top-up with PAYMENT-SIGNATURE
The x402 SDK does the EIP-712 USDC transferWithAuthorization signing for you:
npm install x402
import { createPaymentHeader } from 'x402'
import { Wallet } from 'ethers'
const wallet = new Wallet(process.env.WALLET_KEY!)
// 1. Discover
const discover = await fetch(`${base}/x402/top-up`, { method: 'POST' })
const { accepts } = await discover.json()
const req = accepts.find(a => a.network === 'eip155:8453' || a.network === 'base')
// 2. Sign payment for $10 (write your own amount in base units)
const amount = '10000000' // $10
const header = await createPaymentHeader({ ...req, amount }, wallet)
// 3. Settle
const settle = await fetch(`${base}/x402/top-up`, {
method: 'POST',
headers: { 'PAYMENT-SIGNATURE': header },
})
c
阅读完整来源 ↗