Wallet-Auth
Authentifiziere dich mit einem signierten Sign-In-With-X-Payload im
SIGN-IN-WITH-X-Header.Zahlen mit USDC
Halte ein verfügbares Guthaben mit USDC auf Base oder Solana.
DIEM zuerst
Wenn die Wallet mit einem Venice-Konto mit DIEM-Guthaben verknüpft ist, wird dieses zuerst verbraucht.
Was ist X402?
X402 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)
Schnellstart
Das SDKvenice-x402-client bietet Helfer für Wallet-Auth, Top-ups und Guthaben-Tracking.
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:
Verfügbare Helfer
Das SDK enthält First-Class-Helfer für die häufigsten Venice-x402-Routen. Für alles andererequest() oder createAuthFetch() direkt nutzen.
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: SIGN-IN-WITH-X-Header erstellen
Venice erwartet einen x402-Sign-In-With-X-Nachweis imSIGN-IN-WITH-X-Header: Base64-kodiertes JSON mit den Feldern der signierten Message (domain, address, uri, version, chainId, type, nonce, issuedAt sowie die optionalen Felder expirationTime, notBefore, statement und resources) plus die signature. Venice baut die signierte Message aus diesen Feldern neu auf. EVM-Wallets signieren eine EIP-4361-SIWE-Message auf Base und setzen type auf eip191, auch Smart-Contract-Wallets. Solana-Wallets signieren die Solana-Sign-In-Message mit Ed25519. Im JSON ist chainId der CAIP-2-Identifier (eip155:8453), während die Chain ID-Zeile der signierten Message die reine Referenz (8453) enthält. Der ältere Header-Name X-Sign-In-With-X wird weiterhin akzeptiert, ebenso ältere Payloads, die die signierte message selbst senden.
Jede signierte Message kann nur einmal verwendet werden. Signiere für jede Anfrage eine neue Message mit einer frischen Nonce, entweder deiner eigenen oder der nonce aus der letzten 402-Challenge, und sende sie innerhalb von 5 Minuten nach ihrem issuedAt-Zeitpunkt. Eine wiederverwendete Message gibt 401 zurück (Nonce bereits verwendet), ebenso eine Message, die vor mehr als 5 Minuten ausgestellt wurde.
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 <domain> 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.
createSiwxHeader() unmittelbar vor jeder Anfrage auf. In den folgenden curl-Beispielen muss X402_AUTH für jeden Aufruf ein neu signierter Header sein.
Schritt 2: Guthaben prüfen
Stelle vor einer kostenpflichtigen Anfrage sicher, dass die Wallet ausgabefähiges Guthaben hat:canConsume: ob die Wallet kostenpflichtige Anfragen stellen kannbalanceUsd: aktuelles ausgabefähiges GuthabenminimumTopUpUsdundsuggestedTopUpUsd: Hinweise für Top-upsdiemBalanceUsd: DIEM-gedecktes Guthaben, falls vorhanden
walletAddress akzeptiert entweder eine EVM-Adresse (0x...) oder eine Solana-base58-Adresse.
Schritt 3: Aufladen
Mit USDC auf Base oder Solana aufladen: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 PAYMENT-SIGNATURE-Headers und sende dieselbe Route erneut. Die älteren Header-Namen X-402-Payment und X-PAYMENT werden weiterhin akzeptiert.
PAYMENT-SIGNATURE-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-Paketex402 und viem.
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 einem neu signiertenSIGN-IN-WITH-X-Header auf:
X-Balance-Remaining-Header enthalten.
Schritt 5: Transaktionen einsehen (optional)
Transaktions-Historie der Wallet anzeigen: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.Top-up-Route
Reine Wallet-Routen
Diese Routen nutzenSIGN-IN-WITH-X zur Identifikation, belasten aber kein Guthaben.
Fehler
Für Agenten
Der Flow ist derselbe. Speichere Private Keys in Umgebungsvariablen oder einem Secret Manager, signiere für jede Anfrage eine neue Sign-In-With-X-Message und prüfe das Guthaben vor Anfragen, um unnötige402-Round-Trips zu vermeiden.
Verwandte Ressourcen
x402 Client SDK
Offizieller Venice-x402-Client für Node.js/TypeScript.
API-Preise
Modellpreise und wie Venice Nutzung abrechnet.
Chat Completions
Eine häufige kostenpflichtige Route für Wallet-basierten Zugriff.
API-Spezifikation
Referenz-Dokumentation und Rohdaten der Spezifikation.