agent-payment-x402

Agentenzahlungsabwicklung (x402)

Ermöglicht KI-Agenten richtlinienbasierte Zahlungen mit integrierten Ausgabenkontrollen. Nutzt das x402 HTTP-Zahlungsprotokoll und MCP-Tools, sodass Agenten für externe Dienste, APIs oder andere Agenten ohne Verwahrungsrisiko bezahlen können.

Wann verwenden

Verwenden Sie dies, wenn Ihr Agent für einen API-Aufruf bezahlen, einen Dienst erwerben, mit einem anderen Agenten abrechnen, pro-Task-Ausgabenlimits durchsetzen oder ein nicht-verwahrendes Wallet verwalten muss. Es passt gut zu den Erweiterungen cost-aware-llm-pipeline und security-review.

Entscheidungsbaum

Wählen Sie den Integrationspfad basierend darauf, ob Ihr Agent Zugang zu einer kostenpflichtigen API kauft oder andere für eine API bezahlt:

Bedarf	Empfohlener Pfad
Agent bezahlt eine 402-geschützte API auf Base oder einer anderen vom Agentwallet unterstützten Chain	Verwenden Sie agentwallet-sdk als MCP-Zahlungsserver mit strenger Ausgabenrichtlinie
Agent bezahlt eine 402-geschützte API auf X Layer	Verwenden Sie das OKX Agent Payments Protocol aus okx/onchainos-skills; okx-x402-payment ist ein veralteter Legacy-Alias
TypeScript-API berechnet Agenten	Verwenden Sie die OKX Payments TypeScript-Verkäufer-SDK-Dokumentation für Express, Hono, Fastify oder Next.js
Go-API berechnet Agenten	Verwenden Sie die OKX Payments Go-Verkäufer-SDK-Dokumentation für Gin, Echo oder net/http
Rust-API berechnet Agenten	Verwenden Sie die OKX Payments Rust-Verkäufer-SDK-Dokumentation für Axum
Java-API berechnet Agenten	Verwenden Sie die OKX Payments Java-Verkäufer-SDK-Dokumentation für Spring Boot 2/3, Java EE oder Jakarta
Python-API berechnet Agenten	Überprüfen Sie vor der Implementierung das aktuelle OKX Payments-Repository; ein Python-Verkäuferleitfaden ist möglicherweise nicht verfügbar

Unterstützte Netzwerke

• agentwallet-sdk: Verwenden Sie die Paketdokumentation, um die aktuelle Netzabdeckung vor der Produktion zu bestätigen. Base Sepolia ist der sicherste Entwicklungsstandard; Base Mainnet ist der Produktionspfad, der von der ursprünglichen Erweiterung genannt wird.
• OKX Payments / X Layer: Aktuelle Verkäuferdokumentation zielt auf X Layer (eip155:196) und USDT0-Abrechnung ab. Rufen Sie die aktuellen SDK-Dokumente ab, bevor Sie Produktionscode generieren, da Zahlungspakete und Facilitator-Verhalten sich schnell ändern können.

Funktionsweise

x402-Protokoll

x402 erweitert HTTP 402 (Payment Required) zu einem maschinell verhandelbaren Ablauf. Wenn ein Server 402 zurückgibt, verhandelt das Zahlungstool des Agenten den Preis, überprüft das Budget, signiert eine Transaktion und wiederholt den Vorgang nur innerhalb der vom Orchestrator festgelegten Richtlinien- und Bestätigungsgrenzen.

Ausgabenkontrollen

Jeder Zahlungstool-Aufruf setzt eine SpendingPolicy durch:

• Pro-Task-Budget — maximaler Ausgabenbetrag für eine einzelne Agentenaktion
• Pro-Sitzungs-Budget — kumulatives Limit über eine gesamte Sitzung hinweg
• Zugelassene Empfänger — Beschränkung, welche Adressen/Dienste der Agent bezahlen kann
• Ratenbegrenzungen — maximale Transaktionen pro Minute/Stunde

Nicht-verwahrende Wallets

Agenten halten ihre eigenen Schlüssel über ERC-4337 Smart Accounts. Der Orchestrator legt die Richtlinien vor der Delegation fest; der Agent kann nur innerhalb der Grenzen ausgeben. Keine gepoolten Gelder, kein Verwahrungsrisiko.

MCP-Integration

Die Zahlungsschicht stellt standardmäßige MCP-Tools bereit, die in jede Claude Code- oder Agenten-Infrastruktur eingefügt werden können.

Sicherheitshinweis: Fixieren Sie immer die Paketversion. Dieses Tool verwaltet private Schlüssel – nicht fixierte npx-Installationen führen zu Supply-Chain-Risiken.

Option A: agentwallet-sdk (Base / Multi-Chain)

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

Verfügbare Tools (agent-callable)

Tool	Zweck
get_balance	Kontostand des Agenten-Wallets überprüfen
send_payment	Zahlung an Adresse oder ENS senden
check_spending	Verbleibendes Budget abfragen
list_transactions	Prüfpfad aller Zahlungen

Hinweis: Die Ausgabenrichtlinie wird vom Orchestrator festgelegt, bevor sie an den Agenten delegiert wird – nicht vom Agenten selbst. Dies verhindert, dass Agenten ihre eigenen Ausgabenlimits erhöhen. Konfigurieren Sie die Richtlinie über set_policy in Ihrer Orchestrierungsschicht oder in einem Pre-Task-Hook, niemals als ein vom Agenten aufrufbares Tool.

Option B: OKX Agent Payments Protocol (X Layer)

Verwenden Sie diesen Pfad für X Layer x402, Multi-Party Payment (MPP), Session Payment, Charge und A2A Charge-Abläufe.

Für kundenseitige Agentenabläufe:

1. Installieren Sie das aktuelle okx/onchainos-skills-Repository oder referenzieren Sie es.
2. Verwenden Sie skills/okx-agent-payments-protocol/SKILL.md als Dispatcher.
3. Behandeln Sie skills/okx-x402-payment/SKILL.md als veralteten Kompatibilitätsalias, nicht als kanonische Erweiterung.
4. Fordern Sie explizite Benutzerbestätigung vor Wallet-Statusprüfungen oder Zahlungsaktionen an. Verstecken Sie Zahlungsausführungen nicht hinter einem generischen Tool-Aufruf.

Für verkäuferseitige API-Abläufe rufen Sie vor der Codegenerierung den aktuellen sprachspezifischen Leitfaden ab:

Laufzeit	Aktueller Leitfaden
TypeScript	https://raw.githubusercontent.com/okx/payments/main/typescript/SELLER.md
Go	https://raw.githubusercontent.com/okx/payments/main/go/x402/SELLER.md
Rust	https://raw.githubusercontent.com/okx/payments/main/rust/x402/SELLER.md
Java	https://raw.githubusercontent.com/okx/payments/main/java/SELLER.md

Kopieren Sie keine Beispiele aus älteren Dokumentationen, ohne das aktuelle OKX-Repository zu überprüfen. Die aktuelle OKX-Anleitung verwendet okx-agent-payments-protocol als Dispatcher, und Java-Verkäuferdokumentation ist jetzt verfügbar.

Beispiele

Budgetdurchsetzung in einem MCP-Client

Wenn Sie einen Orchestrator erstellen, der den agentpay MCP-Server aufruft, setzen Sie Budgets durch, bevor Sie kostenpflichtige Tool-Aufrufe auslösen.

Voraussetzungen: Installieren Sie das Paket, bevor Sie die MCP-Konfiguration hinzufügen – npx ohne -y wird in nicht-interaktiven Umgebungen zur Bestätigung auffordern, was dazu führt, dass der Server hängt: npm install -g [email protected]

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. Anmeldeinformationen vor dem Erstellen des Transports validieren.
  //    Ein fehlender Schlüssel muss sofort fehlschlagen – lassen Sie den Teilprozess niemals ohne Authentifizierung starten.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY ist nicht gesetzt – Zahlungsserver wird nicht gestartet");
  }

  // Verbinden zum agentpay MCP-Server über stdio-Transport.
  // Erlauben Sie nur die Umgebungsvariablen, die der Server benötigt – leiten Sie niemals das gesamte process.env
  // an einen Drittanbieter-Teilprozess weiter, der private Schlüssel verwaltet.
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["[email protected]"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
  await agentpay.connect(transport);

  // 2. Ausgabenrichtlinie vor der Delegation an den Agenten festlegen.
  //    Überprüfen Sie immer den Erfolg – ein stiller Fehler bedeutet, dass keine Kontrollen aktiv sind.
  const policyResult = await agentpay.callTool({
    name: "set_policy",
    arguments: {
      per_task_budget: 0.50,
      per_session_budget: 5.00,
      allowlisted_recipients: ["api.example.com"],
    },
  });
  if (policyResult.isError) {
    throw new Error(
      `Fehler beim Festlegen der Ausgabenrichtlinie – Delegation nicht durchführen: ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. PreToolCheck vor jeder kostenpflichtigen Aktion verwenden
  await preToolCheck(agentpay, 0.01);
}

// Pre-Tool-Hook: Fail-Closed-Budgetdurchsetzung mit vier verschiedenen Fehlerpfaden.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Pfad 1: Ungültige Eingabe ablehnen (NaN/Unendlich umgehen den < Vergleich)
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`Ungültige apiCost: ${apiCost} – Aktion blockiert`);
  }

  // Pfad 2: Transport-/Konnektivitätsfehler
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Zahlungsdienst nicht erreichbar – Aktion blockiert: ${err}`);
  }

  // Pfad 3: Tool hat einen Fehler zurückgegeben (z. B. Authentifizierungsfehler, Wallet nicht initialisiert)
  if (result.isError) {
    throw new Error(
      `check_spending fehlgeschlagen – Aktion blockiert: ${JSON.stringify(result.content)}`
    );
  }

  // Pfad 4: Antwortformat parsen und validieren
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("fehlendes oder nicht endliches Feld 'remaining'");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending hat unerwartetes Format zurückgegeben – Aktion blockiert: ${err}`
    );
  }

  // Pfad 5: Budget überschritten
  if (remaining < apiCost) {
    throw new Error(
      `Budget überschritten: Benötigt $${apiCost}, aber nur $${remaining} übrig`
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Best Practices

• Budgets vor der Delegation festlegen: Beim Erstellen von Unter-Agenten fügen Sie über Ihre Orchestrierungsschicht eine SpendingPolicy hinzu. Geben Sie einem Agenten niemals unbegrenzte Ausgaben.
• Abhängigkeiten fixieren: Geben Sie immer eine exakte Version in Ihrer MCP-Konfiguration an (z. B. [email protected]). Überprüfen Sie die Paketintegrität vor der Bereitstellung in der Produktion.
• Prüfpfade: Verwenden Sie list_transactions in Post-Task-Hooks, um zu protokollieren, was ausgegeben wurde und warum.
• Fail Closed: Wenn das Zahlungstool nicht erreichbar ist, blockieren Sie die kostenpflichtige Aktion – fallen Sie nicht auf nicht gemessenen Zugriff zurück.
• Kombination mit security-review: Zahlungstools haben hohe Privilegien. Wenden Sie die gleiche Prüfung an wie bei Shell-Zugriff.
• Zuerst mit Testnets testen: Verwenden Sie Base Sepolia für die Entwicklung; wechseln Sie für die Produktion zu Base Mainnet.

Produktionsreferenzen

• npm: agentwallet-sdk
• Eingefügt in NVIDIA NeMo Agent Toolkit: PR #17 – x402-Zahlungstool für NVIDIA-Agentenbeispiele
• Protokollspezifikation: x402.org
• OKX Payments SDKs: okx/payments – TypeScript-, Go-, Rust- und Java-Verkäuferintegrationen für X Layer x402
• OKX Agent Payments Protocol Erweiterung: okx/onchainos-skills
• OKX Payments Übersicht: web3.okx.com/onchainos/dev-docs/payments/overview