X402

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 X-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.

npm install venice-x402-client

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:

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. 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 <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.

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:

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:

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.

export EVM_PRIVATE_KEY=0xYOUR_PRIVATE_KEY

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:

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:

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.

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.

Wallet-Auth

Zahlen mit USDC

DIEM zuerst

​Was ist X402?

​Voraussetzungen

​Schnellstart

​Mit OpenAI-kompatiblen Tools

​Verfügbare Helfer

​Manueller Flow

​Schritt 1: X-Sign-In-With-X-Header erstellen

​Schritt 2: Guthaben prüfen

​Schritt 3: Aufladen

​X-402-Payment-Header für Base erstellen

​Schritt 4: Anfrage stellen

​Schritt 5: Transaktionen einsehen (optional)

​Unterstützte Routen

​Bezahlte Inferenz-Routen

​Top-up-Route

​Reine Wallet-Routen

​Fehler

​Für Agenten

​Verwandte Ressourcen

x402 Client SDK

API-Preise

Chat Completions

API-Spezifikation

Was ist X402?

Voraussetzungen

Schnellstart

Mit OpenAI-kompatiblen Tools

Verfügbare Helfer

Manueller Flow

Schritt 1: X-Sign-In-With-X-Header erstellen

Schritt 2: Guthaben prüfen

Schritt 3: Aufladen

X-402-Payment-Header für Base erstellen

Schritt 4: Anfrage stellen

Schritt 5: Transaktionen einsehen (optional)

Unterstützte Routen

Bezahlte Inferenz-Routen

Top-up-Route

Reine Wallet-Routen

Fehler

Für Agenten

Verwandte Ressourcen