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 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 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()`
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 una prova sign-in-with-x x402 nell’header SIGN-IN-WITH-X: JSON codificato in Base64 con i campi del messaggio firmato (domain, address, uri, version, chainId, type, nonce, issuedAt e i campi opzionali expirationTime, notBefore, statement e resources) più la signature. Venice ricostruisce il messaggio firmato a partire da quei campi. I wallet EVM firmano un messaggio SIWE EIP-4361 su Base e impostano type su eip191, inclusi gli smart contract wallet. I wallet Solana firmano il messaggio di accesso Solana con Ed25519. Nel JSON, chainId è l’identificatore CAIP-2 (eip155:8453), mentre la riga Chain ID del messaggio firmato contiene il riferimento semplice (8453). Il nome di header legacy X-Sign-In-With-X è ancora accettato, così come i payload più vecchi che inviano direttamente il message firmato. Ogni messaggio firmato può essere usato una sola volta. Firma un nuovo messaggio con un nonce nuovo per ogni richiesta, il tuo oppure il nonce dell’ultima challenge 402, e invialo entro 5 minuti dal suo orario issuedAt. Il riutilizzo di un messaggio restituisce 401 (nonce già usato), così come un messaggio emesso più di 5 minuti prima. 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)

async function createSiwxHeader(resourceUrl: string): Promise<string> {
  const now = new Date()
  const fields = {
    domain: 'api.venice.ai',
    address: wallet.address,
    statement: 'Sign in to Venice AI',
    uri: resourceUrl,
    version: '1',
    nonce: generateNonce(),
    issuedAt: now.toISOString(),
    expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
  }

  const message = new SiweMessage({ ...fields, chainId: 8453 }).prepareMessage()
  const signature = await wallet.signMessage(message)

  return Buffer.from(JSON.stringify({ ...fields, chainId: 'eip155:8453', type: 'eip191', signature }), 'utf8').toString('base64')
}

const response = await fetch('https://api.venice.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'SIGN-IN-WITH-X': await createSiwxHeader('https://api.venice.ai/api/v1/chat/completions'),
  },
  body: JSON.stringify({
    model: 'kimi-k2-5',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
})

Chiama createSiwxHeader() immediatamente prima di ogni richiesta. Negli esempi curl seguenti, X402_AUTH deve essere un header appena firmato per ogni chiamata.

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 "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 PAYMENT-SIGNATURE e riprova la stessa route. I nomi di header legacy X-402-Payment e X-PAYMENT sono ancora accettati.

Inviare USDC direttamente a un indirizzo payTo non ricarica il tuo saldo. Il credito viene aggiunto solo quando un PAYMENT-SIGNATURE firmato viene regolato tramite POST /x402/top-up. Sono supportate solo Base e Solana, quindi gli USDC inviati su qualsiasi altra chain, inclusa la mainnet di Ethereum, non vengono accreditati. Le route di saldo e transazioni leggono il registro di Venice e non la chain, quindi dopo un semplice trasferimento non mostrano nulla.

Costruire l’header PAYMENT-SIGNATURE 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 "PAYMENT-SIGNATURE: $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 un header SIGN-IN-WITH-X appena firmato:

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 "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 "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/voices`, `POST /api/v1/audio/complete`, `POST /api/v1/audio/queue`, `POST /api/v1/audio/retrieve`, `POST /api/v1/audio/voice-changer/queue`, `POST /api/v1/audio/voice-changer/retrieve`, `POST /api/v1/audio/voice-changer/complete`
Video	`POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`
Decisioni	`POST /api/v1/decisions`, `POST /api/v1/systemone`
Strumenti	`POST /api/v1/augment/search`, `POST /api/v1/augment/scrape`, `POST /api/v1/augment/text-parser`
RPC blockchain	`POST /api/v1/crypto/rpc/{network}`

Route di ricarica

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

Route solo wallet

Queste route usano 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, scaduto o già usato	Firma un nuovo messaggio `SIGN-IN-WITH-X` con un nonce nuovo per questa richiesta
`402` con `"error": "Authentication required"`	Non è stato inviato alcun header `SIGN-IN-WITH-X` né una chiave API	Aggiungi l’header Sign-In-With-X. Il campo `extensions` della risposta contiene un nuovo nonce da firmare.
`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 `PAYMENT-SIGNATURE` 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, firma un nuovo messaggio Sign-In-With-X per ogni richiesta e controlla il saldo prima delle richieste per evitare round-trip 402 non necessari.

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.

Documentazione

Per iniziare

Testo e chat

Immagini

Video

Audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

X402

Wallet auth

Paga con USDC

DIEM prima

Cos’è X402?

Prerequisiti

Avvio rapido

Con strumenti compatibili con OpenAI

Helper disponibili

Flusso manuale

Step 2: controlla il saldo

Step 3: ricarica

Costruire l’header PAYMENT-SIGNATURE 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

x402 Client SDK

Prezzi dell'API

Chat Completions

Specifica dell'API

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 SIGN-IN-WITH-X

​Step 2: controlla il saldo

​Step 3: ricarica

​Costruire l’header PAYMENT-SIGNATURE 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 SIGN-IN-WITH-X

Step 2: controlla il saldo

Step 3: ricarica

Costruire l’header PAYMENT-SIGNATURE 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