> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # X402 > Accedi all'API Venice senza una chiave API pagando per richiesta con il protocollo x402 e autenticandoti con un wallet crypto su Base. 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. Autenticati con un payload Sign-In-With-X firmato nell'header `X-Sign-In-With-X`. Mantieni il saldo spendibile con USDC su Base o Solana. Se il wallet è collegato a un account Venice con saldo DIEM, viene speso per primo. ## Cos'è X402? [X402](https://www.x402.org/) è 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`](https://github.com/veniceai/x402-client) fornisce helper per autenticazione wallet, ricariche e tracking del saldo. ```bash theme={"system"} npm install venice-x402-client ``` ```typescript theme={"system"} 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: ```typescript theme={"system"} 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. ### Step 1: crea l'header X-Sign-In-With-X 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 ` 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`. ```typescript theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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`. ```bash theme={"system"} export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY ``` ```bash theme={"system"} 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`: ```bash theme={"system"} 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: ```bash theme={"system"} 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 Client x402 ufficiale Venice per Node.js/TypeScript. Controlla i prezzi dei modelli e come Venice fattura l'utilizzo. Una route a pagamento comune per l'accesso basato su wallet. Documentazione di riferimento e accesso alla spec raw.