Zum Hauptinhalt springen
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.

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)
Erwäge, eine dedizierte Wallet für Automatisierung zu verwenden statt deiner Haupt-Treasury-Wallet.

Schnellstart

Das SDK venice-x402-client bietet Helfer für Wallet-Auth, Top-ups und Guthaben-Tracking.
Der Client erzeugt für jede Anfrage einen frischen 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:

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.

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 im SIGN-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.
Rufe 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:
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:
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 PAYMENT-SIGNATURE-Headers und sende dieselbe Route erneut. Die älteren Header-Namen X-402-Payment und X-PAYMENT werden weiterhin akzeptiert.
Wenn du USDC direkt an eine payTo-Adresse sendest, wird dein Guthaben nicht aufgeladen. Guthaben wird nur gutgeschrieben, wenn eine signierte PAYMENT-SIGNATURE über POST /x402/top-up abgewickelt wird. Nur Base und Solana werden unterstützt, daher werden USDC, die auf einer anderen Chain gesendet werden, einschließlich des Ethereum-Mainnets, nicht gutgeschrieben. Die Routen für Guthaben und Transaktionen lesen das Venice-Ledger und nicht die Chain, daher zeigen sie nach einer einfachen Überweisung nichts an.

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-Pakete x402 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 signierten SIGN-IN-WITH-X-Header auf:
Erfolgreiche Antworten können einen X-Balance-Remaining-Header enthalten.

Schritt 5: Transaktionen einsehen (optional)

Transaktions-Historie der Wallet anzeigen:
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

Die folgenden öffentlichen, kostenpflichtigen Venice-Routen unterstützen aktuell x402-Wallet-Authentifizierung.

Top-up-Route

Reine Wallet-Routen

Diese Routen nutzen SIGN-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ötige 402-Round-Trips zu vermeiden.

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.