> ## 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 > Nutzen Sie die Venice API ohne API-Schlüssel — pro Anfrage via x402-Protokoll bezahlen und sich per Krypto-Wallet auf Base authentifizieren. X402 ermöglicht es dir, Venices kostenpflichtige API-Routen zu nutzen, indem du dich per Wallet authentifizierst und ein Prepaid-USDC-Guthaben unterhältst. Kein API-Schlüssel und kein Account erforderlich. Signiere eine Nachricht, lade auf Base oder Solana auf und rufe jede unterstützte Route auf. Authentifiziere dich mit einem signierten Sign-In-With-X-Payload im `X-Sign-In-With-X`-Header. Halte ein verfügbares Guthaben mit USDC auf Base oder Solana. Wenn die Wallet mit einem Venice-Konto mit DIEM-Guthaben verknüpft ist, wird dieses zuerst verbraucht. ## Was ist X402? [X402](https://www.x402.org/) ist ein offener Zahlungsstandard, der es Anwendungen und Agenten ermöglicht, Dienste programmatisch mit Kryptowährung zu bezahlen. Venice implementiert X402, sodass sich Wallets authentifizieren und Inferenz direkt mit USDC auf Base oder Solana bezahlen können. ## Voraussetzungen * Eine Wallet auf Base oder Solana * Nativer Token für Gas auf der gewählten Chain, z. B. ETH auf Base oder SOL auf Solana * USDC auf der gewählten Chain (oder ein bestehendes, DIEM-gedecktes Guthaben aus einem verknüpften Venice-Konto) Erwäge, eine dedizierte Wallet für Automatisierung zu verwenden statt deiner Haupt-Treasury-Wallet. ## Schnellstart Das SDK [`venice-x402-client`](https://github.com/veniceai/x402-client) bietet Helfer für Wallet-Auth, Top-ups und Guthaben-Tracking. ```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) // überspringen, wenn die Wallet bereits Guthaben hat const response = await venice.chat({ model: 'kimi-k2-5', messages: [{ role: 'user', content: 'Hello!' }] }) ``` Der Client erzeugt für jede Anfrage einen frischen `X-Sign-In-With-X`-Header und verfolgt das Guthaben automatisch über die `X-Balance-Remaining`-Response-Header. ### Mit OpenAI-kompatiblen Tools Wenn du ein Tool nutzt, das einen Custom-`fetch` akzeptiert, verwende `createAuthFetch`, um Wallet-Auth zu jeder Anfrage hinzuzufügen: ```typescript theme={"system"} import { createAuthFetch } from 'venice-x402-client' const authFetch = createAuthFetch(process.env.WALLET_KEY) ``` ### Verfügbare Helfer Das SDK enthält First-Class-Helfer für die häufigsten Venice-x402-Routen. Für alles andere `request()` oder `createAuthFetch()` direkt nutzen. | Kategorie | Methoden | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 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()` | | Video | `video.queue()`, `video.retrieve()`, `video.generate()`, `video.complete()`, `video.transcribe()` | | Embeddings | `embeddings()` | | Models | `models()` | | Wallet | `getBalance()`, `getTransactions()`, `topUp()` | *** ## Manueller Flow Wenn du das SDK nicht verwendest oder das zugrunde liegende Protokoll verstehen möchtest – hier der Schritt-für-Schritt-Flow. Bei einer neuen Wallet musst du zuerst aufladen, sofern sie nicht bereits ein DIEM-Guthaben hat. ### Schritt 1: X-Sign-In-With-X-Header erstellen Venice erwartet ein Base64-kodiertes JSON-Payload mit einer signierten Sign-In-With-X-Nachricht. EVM-Wallets signieren eine EIP-4361-SIWE-Message auf Base. Solana-Wallets signieren die Solana-SIWX-Message mit Ed25519. Erzeuge für jeden Anfrage-Flow eine frische Nonce und einen frischen Timestamp. Für Solana setze `chainId` auf `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, füge `type: "ed25519"` in das kodierte JSON-Payload ein und liefere die Ed25519-Signatur als base58 oder base64. Die signierte Message beginnt mit ` wants you to sign in with your Solana account:`, gefolgt von der Wallet-Adresse und den Standard-Feldern `URI`, `Version`, `Chain ID`, `Nonce`, `Issued At` und optional `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) ``` ### Schritt 2: Guthaben prüfen Stelle vor einer kostenpflichtigen Anfrage sicher, dass die Wallet ausgabefähiges Guthaben hat: ```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" ``` Die Antwort enthält: * `canConsume`: ob die Wallet kostenpflichtige Anfragen stellen kann * `balanceUsd`: aktuelles ausgabefähiges Guthaben * `minimumTopUpUsd` und `suggestedTopUpUsd`: Hinweise für Top-ups * `diemBalanceUsd`: DIEM-gedecktes Guthaben, falls vorhanden Der Path-Parameter `walletAddress` akzeptiert entweder eine EVM-Adresse (`0x...`) oder eine Solana-base58-Adresse. ### Schritt 3: Aufladen Mit USDC auf Base oder Solana aufladen: ```bash theme={"system"} curl --request POST \ --url https://api.venice.ai/api/v1/x402/top-up ``` Der erste Aufruf gibt `402 Payment Required` mit einem `PAYMENT-REQUIRED`-Header zurück, der ein `accepts`-Array enthält. Jeder Eintrag beschreibt eine akzeptierte Zahlungsoption inklusive `network`, `asset`, `payTo` und `amount`. Wähle die Base- oder Solana-Option, mit der du zahlen willst, verwende exakt diese Details zum Bau eines `X-402-Payment`-Headers und sende die Anfrage erneut. #### X-402-Payment-Header für Base erstellen Das folgende Skript erzeugt eine signierte x402-Zahlung auf Base und sendet die Top-up-Anfrage. Benötigt die npm-Pakete `x402` und `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" ``` Verwende in der Produktion die jeweils aktuelle `PAYMENT-REQUIRED`-/`accepts`-Antwort als Single Source of Truth, statt diese Werte hart zu kodieren. Für Solana-Top-ups das Payment aus dem im `accepts` zurückgegebenen Solana-Eintrag erzeugen. Solana-Einträge nutzen `network: "solana"`, den USDC-Mint als `asset` und können netzwerkspezifische Metadaten wie `extra.feePayer` enthalten. ### Schritt 4: Anfrage stellen Sobald die Wallet ausgabefähiges Guthaben hat, rufe einen beliebigen unterstützten Endpoint mit dem `X-Sign-In-With-X`-Header auf: ```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." } ] }' ``` Erfolgreiche Antworten können einen `X-Balance-Remaining`-Header enthalten. ### Schritt 5: Transaktionen einsehen (optional) Transaktions-Historie der Wallet anzeigen: ```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" ``` Das Ledger enthält Einträge wie `TOP_UP`, `CHARGE` und `REFUND`. Der Path-Parameter `walletAddress` akzeptiert entweder eine EVM-Adresse (`0x...`) oder eine Solana-base58-Adresse. *** ## Unterstützte Routen ### Bezahlte Inferenz-Routen Die folgenden öffentlichen, kostenpflichtigen Venice-Routen unterstützen aktuell x402-Wallet-Authentifizierung. | Kategorie | 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` | | Video | `POST /api/v1/video/complete`, `POST /api/v1/video/queue`, `POST /api/v1/video/retrieve`, `POST /api/v1/video/transcriptions` | ### Top-up-Route | Endpoint | Auth | Zweck | | -------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `POST /api/v1/x402/top-up` | Erstanfrage: keine. Retry: `X-402-Payment` | USDC-Credits zum ausgabefähigen Guthaben der Wallet via akzeptierter Base- oder Solana-Zahlungsoption hinzufügen | ### Reine Wallet-Routen Diese Routen nutzen `X-Sign-In-With-X` zur Identifikation, belasten aber kein Guthaben. | Endpoint | Zweck | | ----------------------------------------------- | ----------------------------------------------------------------------- | | `GET /api/v1/x402/balance/{walletAddress}` | Ausgabefähiges Guthaben für eine EVM- oder Solana-Wallet-Adresse prüfen | | `GET /api/v1/x402/transactions/{walletAddress}` | Transaktions-Historie für eine EVM- oder Solana-Wallet-Adresse anzeigen | *** ## Fehler | Status | Wahrscheinliche Ursache | Was tun | | ----------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `401` | Fehlerhaftes oder abgelaufenes Sign-In-With-X-Payload | `X-Sign-In-With-X` mit neuer Nonce und Timestamp neu aufbauen | | `402` auf bezahlter Route | Nicht genug Guthaben | Aufladen und erneut versuchen | | `402` auf `/x402/top-up` | Erwartet. Das ist der Zahlungs-Initiations-Flow. | Die zurückgegebenen Zahlungsdetails nutzen, um `X-402-Payment` zu bauen und erneut zu senden | | `403` auf Balance oder Transactions | Wallet-Mismatch | Sicherstellen, dass die authentifizierte Wallet mit dem Path-Parameter `walletAddress` übereinstimmt | | `400` auf Top-up | Fehlerhafter Payment-Header | Aus der jeweils aktuellen `402`-Antwort neu bauen | *** ## Für Agenten Der Flow ist derselbe. Speichere Private Keys in Umgebungsvariablen oder einem Secret Manager und prüfe das Guthaben vor Anfragen, um unnötige `402`-Round-Trips zu vermeiden. *** ## Verwandte Ressourcen Offizieller Venice-x402-Client für Node.js/TypeScript. Modellpreise und wie Venice Nutzung abrechnet. Eine häufige kostenpflichtige Route für Wallet-basierten Zugriff. Referenz-Dokumentation und Rohdaten der Spezifikation.