> ## 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 > Accédez à l'API Venice sans clé d'API en payant par requête avec le protocole x402 et en vous authentifiant avec un wallet crypto sur Base. X402 vous permet d'utiliser les routes API payantes de Venice en vous authentifiant avec un wallet et en maintenant un solde USDC prépayé. Pas de clé API ni de compte requis. Signez un message, rechargez sur Base ou Solana, et appelez n'importe quelle route prise en charge. Authentifiez-vous avec un payload Sign-In-With-X signé dans l'en-tête `X-Sign-In-With-X`. Maintenez un solde dépensable avec de l'USDC sur Base ou Solana. Si le wallet est lié à un compte Venice avec un solde DIEM, ce solde est dépensé en premier. ## Qu'est-ce que X402 ? [X402](https://www.x402.org/) est un standard de paiement ouvert qui permet aux applications et aux agents de payer pour des services de manière programmatique en utilisant des cryptomonnaies. Venice implémente X402 afin que les wallets puissent s'authentifier et payer l'inférence directement avec de l'USDC sur Base ou Solana. ## Prérequis * Un wallet sur Base ou Solana * Du token natif pour le gas sur la chaîne choisie, comme de l'ETH sur Base ou du SOL sur Solana * De l'USDC sur la chaîne choisie (ou un solde existant adossé à du DIEM via un compte Venice lié) Envisagez d'utiliser un wallet dédié à l'automatisation plutôt que votre wallet trésorerie principal. ## Démarrage rapide Le SDK [`venice-x402-client`](https://github.com/veniceai/x402-client) fournit des helpers pour l'auth par wallet, les recharges et le suivi de solde. ```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) // ignorer si le wallet a déjà un solde dépensable const response = await venice.chat({ model: 'kimi-k2-5', messages: [{ role: 'user', content: 'Hello!' }] }) ``` Le client génère un en-tête `X-Sign-In-With-X` frais pour chaque requête et suit automatiquement le solde via les en-têtes de réponse `X-Balance-Remaining`. ### Avec des outils compatibles OpenAI Si vous utilisez un outil qui accepte un `fetch` personnalisé, utilisez `createAuthFetch` pour ajouter l'auth par wallet à n'importe quelle requête : ```typescript theme={"system"} import { createAuthFetch } from 'venice-x402-client' const authFetch = createAuthFetch(process.env.WALLET_KEY) ``` ### Helpers disponibles Le SDK inclut des helpers de première classe pour les routes Venice x402 les plus courantes. Pour tout ce qui n'est pas couvert, utilisez `request()` ou `createAuthFetch()` directement. | Catégorie | Méthodes | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 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()` | | Vidéo | `video.queue()`, `video.retrieve()`, `video.generate()`, `video.complete()`, `video.transcribe()` | | Embeddings | `embeddings()` | | Modèles | `models()` | | Wallet | `getBalance()`, `getTransactions()`, `topUp()` | *** ## Flux manuel Si vous n'utilisez pas le SDK ou si vous avez besoin de comprendre le protocole sous-jacent, voici le flux étape par étape. Pour un nouveau wallet, partez du principe que vous devez d'abord recharger, sauf s'il dispose déjà d'un solde DIEM dépensable. ### Étape 1 : Créer l'en-tête X-Sign-In-With-X Venice attend un payload JSON encodé en Base64 contenant un message Sign-In-With-X signé. Les wallets EVM signent un message SIWE EIP-4361 sur Base. Les wallets Solana signent le message SIWX Solana avec Ed25519. Générez un nonce et un timestamp frais pour chaque flux de requête. Pour Solana, définissez `chainId` à `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, incluez `type: "ed25519"` dans le payload JSON encodé et fournissez la signature Ed25519 en base58 ou base64. Le message signé commence par ` wants you to sign in with your Solana account:`, suivi de l'adresse du wallet et des champs standards `URI`, `Version`, `Chain ID`, `Nonce`, `Issued At` et `Expiration Time` (optionnel). ```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) ``` ### Étape 2 : Vérifier le solde Avant de faire une requête payante, vérifiez que le wallet dispose d'un solde dépensable : ```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 réponse inclut : * `canConsume` : si le wallet peut faire des requêtes payantes * `balanceUsd` : le solde dépensable actuel * `minimumTopUpUsd` et `suggestedTopUpUsd` : indications pour les recharges * `diemBalanceUsd` : le solde adossé à du DIEM, le cas échéant Le paramètre de chemin `walletAddress` accepte une adresse EVM (`0x...`) ou une adresse Solana en base58. ### Étape 3 : Recharger Rechargez avec de l'USDC sur Base ou Solana : ```bash theme={"system"} curl --request POST \ --url https://api.venice.ai/api/v1/x402/top-up ``` Le premier appel renvoie `402 Payment Required` avec un en-tête `PAYMENT-REQUIRED` contenant un tableau `accepts`. Chaque entrée décrit une option de paiement acceptée, notamment `network`, `asset`, `payTo` et `amount`. Choisissez l'option Base ou Solana avec laquelle vous voulez payer, utilisez ces détails exacts pour construire un en-tête `X-402-Payment` et réessayez la même route. #### Construction de l'en-tête X-402-Payment pour Base Le script suivant crée un paiement x402 signé sur Base et envoie la requête de recharge. Nécessite les paquets npm `x402` et `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" ``` En production, utilisez la dernière réponse `PAYMENT-REQUIRED` / `accepts` comme source de vérité au lieu de coder en dur ces valeurs. Pour les recharges Solana, construisez le paiement à partir de l'entrée Solana renvoyée dans `accepts`. Les entrées Solana utilisent `network: "solana"`, le mint USDC comme `asset`, et peuvent inclure des métadonnées spécifiques au réseau comme `extra.feePayer`. ### Étape 4 : Faire une requête Une fois que le wallet dispose d'un solde dépensable, appelez n'importe quel endpoint pris en charge avec l'en-tête `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." } ] }' ``` Les réponses réussies peuvent inclure un en-tête `X-Balance-Remaining`. ### Étape 5 : Inspecter les transactions (facultatif) Consultez l'historique des transactions du 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" ``` Le grand livre inclut des entrées telles que `TOP_UP`, `CHARGE` et `REFUND`. Le paramètre de chemin `walletAddress` accepte une adresse EVM (`0x...`) ou une adresse Solana en base58. *** ## Routes prises en charge ### Routes d'inférence payantes Les routes Venice publiques payantes suivantes prennent actuellement en charge l'authentification par wallet x402. | Catégorie | Endpoints | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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` | | Vidéo | `POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`, `POST /api/v1/video/transcriptions` | ### Route de recharge | Endpoint | Auth | Objectif | | -------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `POST /api/v1/x402/top-up` | Requête initiale : aucune. Réessai : `X-402-Payment` | Ajouter des crédits USDC au solde dépensable du wallet via une option de paiement Base ou Solana acceptée | ### Routes wallet uniquement Ces routes utilisent `X-Sign-In-With-X` pour l'identité mais ne facturent pas le solde. | Endpoint | Objectif | | ----------------------------------------------- | -------------------------------------------------------------------------------- | | `GET /api/v1/x402/balance/{walletAddress}` | Vérifier le solde dépensable pour une adresse de wallet EVM ou Solana | | `GET /api/v1/x402/transactions/{walletAddress}` | Consulter l'historique des transactions pour une adresse de wallet EVM ou Solana | *** ## Erreurs | Statut | Cause probable | Que faire | | --------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `401` | Payload Sign-In-With-X malformé ou expiré | Reconstruire `X-Sign-In-With-X` avec un nonce et un timestamp frais | | `402` sur une route payante | Solde dépensable insuffisant | Rechargez et réessayez | | `402` sur `/x402/top-up` | Attendu. C'est le flux d'initiation de paiement. | Utilisez les détails de paiement renvoyés pour construire `X-402-Payment` et réessayez | | `403` sur balance ou transactions | Wallet incohérent | Assurez-vous que le wallet authentifié correspond au paramètre de chemin `walletAddress` | | `400` sur la recharge | En-tête de paiement malformé | Reconstruisez à partir de la dernière réponse `402` | *** ## Pour les agents Le flux est identique. Stockez les clés privées dans des variables d'environnement ou un gestionnaire de secrets, et vérifiez le solde avant les requêtes pour éviter des allers-retours `402` inutiles. *** ## Ressources connexes Client x402 officiel Venice pour Node.js/TypeScript. Consultez la tarification des modèles et la manière dont Venice facture l'usage. Une route payante courante pour l'accès basé sur wallet. Documentation de référence et accès au spec brut.