x402-Zahlungsprotokoll

Was macht x402-Zahlungsprotokoll?

x402 ermöglicht sofortige Stablecoin-Zahlungen direkt über HTTP unter Verwendung des HTTP-Statuscodes 402 Payment Required. Perfekt für KI-Agenten, die APIs, Daten oder Rechenleistung on-demand bezahlen.

Schnellstart

SDK installieren

npm install x402
# oder
pnpm add x402

Umgebungsvariablen einrichten

# Wallet-Private-Key sicher speichern
export WALLET_PRIVATE_KEY="0x..."

# Optional: Netzwerk-RPC angeben
export BASE_RPC_URL="https://mainnet.base.org"

So funktioniert x402

1. Anfrage → Der Client ruft eine kostenpflichtige API auf
2. 402-Antwort → Der Server sendet Zahlungsdetails im PAYMENT-REQUIRED-Header
3. Bezahlen & Wiederholen → Der Client signiert die Zahlung und wiederholt die Anfrage mit dem PAYMENT-SIGNATURE-Header
4. Zugriff → Der Server verifiziert, wickelt die Zahlung ab und gibt die Ressource frei

x402-Client verwenden

TypeScript/Node.js

import { x402Client } from 'x402';

const client = x402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'base', // oder 'ethereum', 'arbitrum', etc.
});

// Automatische 402-Behandlung
const response = await client.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();

Mit fetch-Wrapper

import { wrapFetch } from 'x402';

const fetch402 = wrapFetch(fetch, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
});

// Wie normales fetch verwenden – 402 wird automatisch behandelt
const res = await fetch402('https://paid-api.com/data');

Manueller Ablauf (curl)

Schritt 1: Zahlungsanforderungen ermitteln

curl -i https://api.example.com/paid-resource
# Gibt 402 mit PAYMENT-REQUIRED-Header zurück (base64-JSON)

Schritt 2: Zahlungsdetails decodieren

# Der PAYMENT-REQUIRED-Header enthält base64-codiertes JSON:
# {
#   "amount": "1000000",      # 1 USDC (6 Dezimalstellen)
#   "currency": "USDC",
#   "network": "base",
#   "recipient": "0x...",
#   "scheme": "exact"
# }

Schritt 3: Signieren und bezahlen

# x402-CLI oder SDK verwenden, um Zahlungssignatur zu erstellen
npx x402 pay \
  --amount 1000000 \
  --recipient 0x... \
  --network base

Schritt 4: Mit Nachweis wiederholen

curl -H "PAYMENT-SIGNATURE: <base64_payload>" \
  https://api.example.com/paid-resource

Häufige Muster

Für API-Aufrufe bezahlen

// Wetter-API, die 0,001 USDC pro Aufruf kostet
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');

Für KI-Inferenz bezahlen

// LLM-API mit token-basierter Preisgestaltung
const completion = await client.fetch('https://llm.example.com/v1/chat', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'Hello' }),
});

Guthaben vor dem Bezahlen prüfen

import { getBalance } from 'x402';

const balance = await getBalance({
  address: walletAddress,
  network: 'base',
  token: 'USDC',
});

if (balance < requiredAmount) {
  console.log('Unzureichendes USDC-Guthaben');
}

Unterstützte Netzwerke

Netzwerk	Chain-ID	Status
Base	8453	✅ Primär
Ethereum	1	✅ Unterstützt
Arbitrum	42161	✅ Unterstützt
Optimism	10	✅ Unterstützt
Polygon	137	✅ Unterstützt

Zahlungsschemata

• exact: Festen Betrag bezahlen (z. B. 0,01 $ pro API-Aufruf)
• upto: Bis zu einem Maximalbetrag basierend auf Nutzung bezahlen (z. B. LLM-Tokens)
• subscription: Wallet-basierter Zugriff mit Sitzungen (V2)

Fehlerbehandlung

try {
  const res = await client.fetch(url);
} catch (err) {
  if (err.code === 'INSUFFICIENT_BALANCE') {
    // Wallet muss aufgeladen werden
  } else if (err.code === 'PAYMENT_FAILED') {
    // Transaktion ist on-chain fehlgeschlagen
  } else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
    // Server hat fehlerhafte 402-Antwort gesendet
  }
}

Sicherheitshinweise

• Private Keys niemals in Logs oder im Chat offenlegen
• Umgebungsvariablen für Wallet-Anmeldedaten verwenden
• op run oder ähnliches zur geheimen Injektion bevorzugen
• Zahlungsbeträge vor Bestätigung großer Transaktionen überprüfen

V2-Funktionen (Dezember 2025)

• Wallet-basierte Identität: Nicht bei jedem Aufruf erneut bezahlen müssen – mit Sitzungen
• Auto-Erkennung: APIs legen Zahlungsmetadaten unter /.well-known/x402 offen
• Multi-Facilitator: Auswahl zwischen Zahlungsabwicklern
• CAIP-Standards: Universelle Chain/Asset-Identifikatoren

Ressourcen

• Spezifikation: https://github.com/coinbase/x402
• Dokumentation: https://docs.cdp.coinbase.com/x402
• Demo-APIs: https://www.x402.org