Dashboard
DE
Gratis starten

Wie ein KI-Agent eine Websuche pro Aufruf mit x402 bezahlt

Kein Account, kein API-Key: die echte 402-Challenge, die FastAF zurückgibt, der Node-Client, der sie in USDC auf Base bezahlt, und wie du deckelst, was der Agent pro Aufruf ausgeben darf.

Ein Agent, der eine einzige Google-Suche braucht, sollte dafür kein Anmeldeformular, keinen API-Key im Secrets-Manager und kein Prepaid-Guthaben brauchen. Mit x402 schickt er den Request, bekommt einen Preis zurück, bezahlt ihn aus seiner eigenen Wallet und erhält die Daten. Hier ist der komplette Ablauf gegen FastAF, mit der echten Challenge und echtem Client-Code.

Was ist x402?

x402 holt den HTTP-Status 402 Payment Required zurück, der jahrzehntelang ungenutzt in der Spezifikation lag. Der Server beantwortet einen unbezahlten Request mit 402 und einem maschinenlesbaren Preis; der Client bezahlt und wiederholt denselben Request. In Version 2 des Protokolls läuft das über drei Header, jeweils base64-kodiertes JSON: PAYMENT-REQUIRED (Server an Client, der Preis), PAYMENT-SIGNATURE (Client an Server, die signierte Zahlung) und PAYMENT-RESPONSE (Server an Client, das Ergebnis der Abwicklung), so beschrieben auf docs.x402.org, geprüft am 19. Oktober 2026.

Die Zahlung selbst ist eine Stablecoin-Überweisung, in der Praxis USDC auf Base. Der Client signiert eine Autorisierung; ein Facilitator prüft sie gegen die Anforderungen des Servers und reicht sie on-chain ein. Die Facilitator-Docs stellen klar, dass er „keine Gelder hält und nicht als Verwahrer agiert”. Das Protokoll entstand bei Coinbase und wurde an die x402 Foundation unter dem Dach der Linux Foundation übergeben, angekündigt am 2. April 2026, und steht unter der Apache-2.0-Lizenz.

Wie sieht die 402-Challenge aus?

Jeder FastAF-Endpoint ist unter https://api.fastaf.co/x402/v1/{endpoint} erreichbar, mit denselben Parametern wie die API mit Key. Der erste Request kostet nichts:

curl -i "https://api.fastaf.co/x402/v1/serp?query=x402+payment+protocol"

Am 19. Oktober 2026 kam das als HTTP/2 402 in 0,24 Sekunden zurück. Den payment-required-Header dekodiert, ergibt sich (gekürzt):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x05B75e13f071A09A26B50a18Ce5BD02a0755d76F",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Feld für Feld:

  • scheme: "exact": genau diesen Betrag zahlen, nicht mehr.
  • network: "eip155:8453": das Base-Mainnet, in CAIP-2-Notation.
  • amount: "5000": atomare Einheiten. USDC hat 6 Dezimalstellen, 5000 sind also 0,005 $, der Preis einer Suche.
  • asset: der USDC-Contract auf Base. Die SDK-eigene Tabelle der Standard-Assets führt dieselbe Adresse als USDC.
  • payTo: die Adresse, die die Zahlung empfängt.
  • maxTimeoutSeconds: 300: Die signierte Autorisierung gilt fünf Minuten.
  • extra.name und extra.version: die EIP-712-Domain des Tokens, die der Client braucht, um eine gültige Transfer-Autorisierung zu signieren.

Ein Detail, das man kennen sollte: Die Parameter werden validiert, bevor überhaupt ein Preis genannt wird. Dieselbe URL ohne q lieferte 400 invalid_parameters, keine 402, ein Agent wird also nie gebeten, für einen fehlerhaften Request zu zahlen.

Wie bezahlt der Agent sie in Node?

Die offiziellen Pakete übernehmen Parsing, Signatur und Retry. Die Versionen unten sind die aktuellen auf npm (@x402/fetch 2.28.0, @x402/core und @x402/evm in derselben Version):

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.AGENT_WALLET_KEY),
  networks: ["eip155:8453"],
});

// Jede einzelne Zahlung über einem Cent ablehnen.
client.setSpendControls({ maxAmountPerPayment: "$0.01" });

// Nicht mehr zahlen, sobald dieser Lauf 0,05 $ ausgegeben hat (atomare USDC-Einheiten).
let spent = 0n;
client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
  const amount = BigInt(selectedRequirements.amount);
  if (spent + amount > 50_000n) return { abort: true, reason: "run budget exhausted" };
  spent += amount;
});

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPayment("https://api.fastaf.co/x402/v1/serp?query=x402+payment+protocol");
console.log(res.status, res.headers.get("X-FastAF-Credits-Used"));

Ohne setSpendControls deckelt @x402/core jede Zahlung bereits auf DEFAULT_MAX_AMOUNT_PER_PAYMENT, im installierten Quellcode "$1". Für eine Such-API ist das viel zu großzügig; setz den Wert auf das, was dein teuerster Aufruf kostet.

Wir haben dieses Skript am 19. Oktober 2026 mit einer frisch erzeugten Wallet ohne USDC ausgeführt. Ein bezahlter Aufruf kam also nicht zustande, und die 200-Antwort mit dem PAYMENT-RESPONSE-Beleg ist das, was das SDK mit einer gedeckten Wallet tut. Was tatsächlich passierte: Mit dem Limit bei $0.002 lehnte das SDK lokal in 91 ms ab, bevor irgendetwas signiert wurde („rejected by spendControls.maxAmountPerPayment”). Mit dem Limit bei $0.01 parste es die 402, signierte, versuchte es erneut, und der Server antwortete wieder mit 402 und invalid_exact_evm_insufficient_balance. Keine Suche lief, nichts wurde abgewickelt.

Warum ist „nur bei Erfolg abgerechnet” für Agenten wichtig?

Agenten scheitern bei vielen Aufrufen: eine schlechte Query, eine Seite mit Timeout, ein nicht erlaubtes Ziel. Bei FastAF wird die signierte Zahlung erst abgewickelt, nachdem der Upstream-Request erfolgreich war. Schlägt der Aufruf fehl, wird die Autorisierung nie eingereicht und verfällt nach maxTimeoutSeconds, die Wallet behält ihr Geld. Die API mit Key folgt derselben Regel: Fehlgeschlagene Requests werden nie abgerechnet.

Die Preise entsprechen den Credit-Kosten der API mit Key, zu 0,001 $ pro Credit. Diese Beträge stammen aus Live-Challenges vom 19. Oktober 2026:

Request Credits x402-Betrag Preis
/scrape, statische Seite 1 1000 0,001 $
/serp, Google-Suche 5 5000 0,005 $
/shopping 10 10000 0,01 $
/linkedin-Profil 60 60000 0,06 $

Wann sind Prepaid-Credits die bessere Wahl?

x402 passt für einen Agenten, der gelegentlich Aufrufe macht, irgendwo läuft, wo du keinen Key hinterlegen kannst, oder aus seinem eigenen Budget zahlen soll. Prepaid-Credits gewinnen in drei Fällen:

  • Volumen. Ein Starter-Paket für 10 $ sind 20.000 Credits, 1.000 Suchen kosten also 2,50 $ statt 5,00 $ über x402, und 1,50 $ mit dem Pro-Paket. Credits bleiben 12 Monate gültig, kein Abo.
  • MCP. Der gehostete MCP-Server unter https://api.fastaf.co/mcp authentifiziert mit einem Bearer-Key; x402-Zahlungen nimmt er nicht an.
  • Ein hartes Limit auf dem Account. Ein aufgebrauchtes Guthaben liefert 402 insufficient_credits und stoppt, egal was der Agent entscheidet. Der Beitrag zum Ausgabenlimit zeigt, wie du das mit einem Budget pro Lauf kombinierst.

Wie hältst du die Wallet des Agenten sicher?

Der Private Key liegt in der Umgebung des Agenten und signiert, ohne jemanden zu fragen. Behandle ihn also wie eine Hot Wallet:

  • Nimm pro Agent eine eigene Wallet, nie eine, auf der noch etwas anderes liegt.
  • Lade sie mit kleinen Beträgen auf und füll sie bewusst nach; das Guthaben ist dein Worst Case.
  • Setz maxAmountPerPayment auf den Preis deines teuersten Aufrufs, dazu ein Budget pro Lauf im Hook.
  • Leg networks auf eip155:8453 fest, damit der Client nie auf einer Chain zahlt, die du nicht eingeplant hast.

Kurzversion

x402 macht aus einer 402-Antwort ein Preisschild: PAYMENT-REQUIRED dekodieren, die USDC-Autorisierung signieren, mit PAYMENT-SIGNATURE erneut senden. Bei FastAF kostet eine Suche 0,005 $, abgerechnet nur bei Erfolg, und die Spend Controls des SDK deckeln jede Zahlung, bevor irgendetwas signiert wird. Der komplette Ablauf steht im x402-Abschnitt, jeder Preis unter Preise. Für Volumen oder MCP erstellst du einen kostenlosen Account und startest mit 500 Credits, ohne Karte.