X402

X402 ti permette di usare le route API a pagamento di Venice autenticandoti con un wallet e mantenendo un saldo USDC prepagato. Non sono richiesti API key o account. Firma un messaggio, ricarica su Base o Solana e chiama qualsiasi route supportata.

Wallet auth

Autenticati con un payload Sign-In-With-X firmato nell’header X-Sign-In-With-X.

Paga con USDC

Mantieni il saldo spendibile con USDC su Base o Solana.

DIEM prima

Se il wallet è collegato a un account Venice con saldo DIEM, viene speso per primo.

Cos’è X402?

X402 è uno standard di pagamento aperto che consente ad applicazioni e agenti di pagare i servizi in modo programmatico usando criptovalute. Venice implementa X402 in modo che i wallet possano autenticarsi e pagare l’inferenza direttamente con USDC su Base o Solana.

Prerequisiti

Un wallet su Base o Solana
Token nativo per il gas sulla chain selezionata, come ETH su Base o SOL su Solana
USDC sulla chain selezionata (o saldo DIEM esistente da un account Venice collegato)

Considera l’uso di un wallet dedicato per l’automazione invece del tuo wallet di tesoreria principale.

Avvio rapido

L’SDK venice-x402-client fornisce helper per autenticazione wallet, ricariche e tracking del saldo.

npm install venice-x402-client

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

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

await venice.topUp(10) // salta se il wallet ha già saldo spendibile

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

Il client genera un nuovo header X-Sign-In-With-X per ogni richiesta e traccia automaticamente il saldo dagli header di risposta X-Balance-Remaining.

Con strumenti compatibili con OpenAI

Se stai usando uno strumento che accetta un fetch personalizzato, usa createAuthFetch per aggiungere l’autenticazione wallet a qualsiasi richiesta:

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

const authFetch = createAuthFetch(process.env.WALLET_KEY)

Helper disponibili

L’SDK include helper di prima classe per le route Venice x402 più comuni. Per tutto ciò che non è coperto, usa request() o createAuthFetch() direttamente.

Categoria	Metodi
Chat	`chat()`, `chatStream()`
Responses	`responses.create()`, `responses.stream()`
Immagini	`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()`
Modelli	`models()`
Wallet	`getBalance()`, `getTransactions()`, `topUp()`

Flusso manuale

Se non stai usando l’SDK o hai bisogno di capire il protocollo sottostante, ecco il flusso passo dopo passo. Per un nuovo wallet, assumi di dover prima ricaricare a meno che non abbia già saldo DIEM spendibile. Venice si aspetta un payload JSON codificato in Base64 contenente un messaggio Sign-In-With-X firmato. I wallet EVM firmano un messaggio SIWE EIP-4361 su Base. I wallet Solana firmano il messaggio Solana SIWX con Ed25519. Genera un nuovo nonce e timestamp per ogni flusso di richiesta. Per Solana, imposta chainId su solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, includi type: "ed25519" nel payload JSON codificato e fornisci la firma Ed25519 come base58 o base64. Il messaggio firmato inizia con <domain> wants you to sign in with your Solana account:, seguito dall’indirizzo del wallet e dai campi standard URI, Version, Chain ID, Nonce, Issued At e dal campo opzionale 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)

Step 2: controlla il saldo

Prima di fare una richiesta a pagamento, verifica che il wallet abbia saldo spendibile:

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"

La risposta include:

canConsume: se il wallet può fare richieste a pagamento
balanceUsd: saldo spendibile corrente
minimumTopUpUsd e suggestedTopUpUsd: linee guida per le ricariche
diemBalanceUsd: saldo basato su DIEM, se presente

Il parametro di path walletAddress accetta sia un indirizzo EVM (0x...) sia un indirizzo Solana base58.

Step 3: ricarica

Ricarica con USDC su Base o Solana:

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

La prima chiamata restituisce 402 Payment Required con un header PAYMENT-REQUIRED contenente un array accepts. Ogni voce descrive un’opzione di pagamento accettata, inclusi network, asset, payTo e amount. Scegli l’opzione Base o Solana con cui vuoi pagare, usa questi dettagli esatti per costruire un header X-402-Payment e riprova la stessa route.

Costruire l’header X-402-Payment per Base

Lo script seguente crea un pagamento x402 firmato su Base e invia la richiesta di ricarica. Richiede i pacchetti npm x402 e viem.

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"

Usa l’ultima risposta PAYMENT-REQUIRED / accepts come fonte di verità in produzione invece di hardcodare questi valori. Per le ricariche Solana, costruisci il pagamento dalla voce Solana restituita in accepts. Le voci Solana usano network: "solana", il mint USDC come asset e possono includere metadati specifici della rete come extra.feePayer.

Step 4: fai una richiesta

Una volta che il wallet ha saldo spendibile, chiama qualsiasi endpoint supportato con l’header 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."
      }
    ]
  }'

Le risposte di successo possono includere un header X-Balance-Remaining.

Step 5: ispeziona le transazioni (opzionale)

Esamina lo storico delle transazioni del wallet:

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"

Il registro include voci come TOP_UP, CHARGE e REFUND. Il parametro di path walletAddress accetta sia un indirizzo EVM (0x...) sia un indirizzo Solana base58.

Route supportate

Route di inferenza a pagamento

Le seguenti route pubbliche a pagamento di Venice supportano attualmente l’autenticazione tramite wallet x402.

Categoria	Endpoint
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`

Route di ricarica

Endpoint	Auth	Scopo
`POST /api/v1/x402/top-up`	Richiesta iniziale: nessuna. Retry: `X-402-Payment`	Aggiungi crediti USDC al saldo spendibile del wallet usando un’opzione di pagamento Base o Solana accettata

Route solo wallet

Queste route usano X-Sign-In-With-X per l’identità ma non addebitano il saldo.

Endpoint	Scopo
`GET /api/v1/x402/balance/{walletAddress}`	Controlla il saldo spendibile per un indirizzo wallet EVM o Solana
`GET /api/v1/x402/transactions/{walletAddress}`	Visualizza lo storico delle transazioni per un indirizzo wallet EVM o Solana

Errori

Stato	Causa probabile	Cosa fare
`401`	Payload Sign-In-With-X malformato o scaduto	Ricostruisci `X-Sign-In-With-X` con un nuovo nonce e timestamp
`402` su una route a pagamento	Saldo spendibile insufficiente	Ricarica e ritenta
`402` su `/x402/top-up`	Atteso. Questo è il flusso di avvio del pagamento.	Usa i dettagli di pagamento restituiti per costruire `X-402-Payment` e ritenta
`403` su balance o transactions	Mismatch del wallet	Assicurati che il wallet autenticato corrisponda al parametro di path `walletAddress`
`400` su top-up	Header di pagamento malformato	Ricostruisci dall’ultima risposta `402`

Per gli agenti

Il flusso è lo stesso. Memorizza le chiavi private in variabili d’ambiente o in un secret manager e controlla il saldo prima delle richieste per evitare round-trip 402 non necessari.

Risorse correlate

x402 Client SDK

Client x402 ufficiale Venice per Node.js/TypeScript.

Prezzi dell'API

Controlla i prezzi dei modelli e come Venice fattura l’utilizzo.

Chat Completions

Una route a pagamento comune per l’accesso basato su wallet.

Specifica dell'API

Documentazione di riferimento e accesso alla spec raw.

Wallet auth

Paga con USDC

DIEM prima

​Cos’è X402?

​Prerequisiti

​Avvio rapido

​Con strumenti compatibili con OpenAI

​Helper disponibili

​Flusso manuale

​Step 1: crea l’header X-Sign-In-With-X

​Step 2: controlla il saldo

​Step 3: ricarica

​Costruire l’header X-402-Payment per Base

​Step 4: fai una richiesta

​Step 5: ispeziona le transazioni (opzionale)

​Route supportate

​Route di inferenza a pagamento

​Route di ricarica

​Route solo wallet

​Errori

​Per gli agenti

​Risorse correlate

x402 Client SDK

Prezzi dell'API

Chat Completions

Specifica dell'API

Cos’è X402?

Prerequisiti

Avvio rapido

Con strumenti compatibili con OpenAI

Helper disponibili

Flusso manuale

Step 1: crea l’header X-Sign-In-With-X

Step 2: controlla il saldo

Step 3: ricarica

Costruire l’header X-402-Payment per Base

Step 4: fai una richiesta

Step 5: ispeziona le transazioni (opzionale)

Route supportate

Route di inferenza a pagamento

Route di ricarica

Route solo wallet

Errori

Per gli agenti

Risorse correlate