agent-payment-x402

Agent Payment Execution (x402)

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

Verwendung

Verwenden, wenn: Ihr Agent einen API-Aufruf bezahlen, einen Dienst kaufen, mit einem anderen Agenten abrechnen, Aufgabenausgabenlimits durchsetzen oder ein nicht-verwahrendes Wallet verwalten muss. Passt natürlicherweise zu den Fähigkeiten 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 anderen eine solche in Rechnung stellt:

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 veraltetes Legacy-Alias
TypeScript-API stellt Agenten in Rechnung	Verwenden Sie die OKX Payments TypeScript-Verkäufer-SDK-Dokumentation für Express, Hono, Fastify oder Next.js
Go-API stellt Agenten in Rechnung	Verwenden Sie die OKX Payments Go-Verkäufer-SDK-Dokumentation für Gin, Echo oder net/http
Rust-API stellt Agenten in Rechnung	Verwenden Sie die OKX Payments Rust-Verkäufer-SDK-Dokumentation für Axum
Java-API stellt Agenten in Rechnung	Verwenden Sie die OKX Payments Java-Verkäufer-SDK-Dokumentation für Spring Boot 2/3, Java EE oder Jakarta
Python-API stellt Agenten in Rechnung	Überprüfen Sie vor der Implementierung das aktuelle OKX Payments Repository; ein Python-Verkäufer-Leitfaden 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 Entwicklungstandard; Base Mainnet ist der vom ursprünglichen Skill genannte Produktionspfad.
• OKX Payments / X Layer: Aktuelle Verkäuferdokumentation zielt auf X Layer (eip155:196) und USDT0-Abrechnung. Rufen Sie vor der Generierung von Produktionscode die aktuellen SDK-Dokumente ab, da sich Zahlungspakete und Facilitator-Verhalten schnell ändern können.

Funktionsweise

x402-Protokoll

x402 erweitert HTTP 402 (Payment Required) zu einem maschinenverhandelbaren Ablauf. Wenn ein Server 402 zurückgibt, verhandelt das Zahlungswerkzeug 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 Zahlungswerkzeugaufruf erzwingt eine SpendingPolicy:

• Aufgabenbudget — maximaler Ausgabenbetrag für eine einzelne Agentenaktion
• Sitzungsbudget — kumulative Grenze über eine gesamte Sitzung hinweg
• Whitelist-Empfänger — beschränkt, welche Adressen/Dienste der Agent bezahlen kann
• Ratenbegrenzungen — maximale Transaktionen pro Minute/Stunde

Nicht-verwahrende Wallets

Agenten verwalten ihre eigenen Schlüssel über ERC-4337 Smart Accounts. Der Orchestrator legt die Richtlinie vor der Delegation fest; der Agent kann nur innerhalb der Grenzen Ausgaben tätigen. Keine gepoolten Gelder, kein Verwahrungsrisiko.

MCP-Integration

Die Zahlungsschicht stellt Standard-MCP-Werkzeuge bereit, die in jede Claude Code- oder Agenten-Toolchain passen.

Sicherheitshinweis: Verwenden Sie immer eine feste Paketversion. Dieses Werkzeug verwaltet private Schlüssel — nicht festgelegte npx-Installationen führen zu Supply-Chain-Risiken.

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

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

Verfügbare Werkzeuge (agentenaufrufbar)

Werkzeug	Zweck
get_balance	Agenten-Wallet-Guthaben abfragen
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 vor der Delegation an den Agenten festgelegt — nicht vom Agenten selbst. Dies verhindert, dass Agenten ihre eigenen Ausgabenlimits erhöhen. Konfigurieren Sie die Richtlinie über set_policy in Ihrer Orchestrierungsschicht oder im Pre-Task-Hook, nie als agentenaufrufbares Werkzeug.

Option B: OKX Agent Payments Protocol (X Layer)

Verwenden Sie diesen Pfad für X Layer x402, Multi-Party Payment (MPP), Sitzungszahlung, Abbuchung und A2A-Abbuchungsflüsse.

Für kundenseitige Agentenflüsse:

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 veraltetes Kompatibilitätsalias, nicht als kanonischen Skill.
4. Fordern Sie explizite Benutzerbestätigung vor Wallet-Statusprüfungen oder Zahlungsaktionen an. Verstecken Sie die Zahlungsausführung nicht hinter einem generischen Werkzeugaufruf.

Für verkäuferseitige API-Flüsse 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 Dokumenten, 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 Werkzeugaufrufe ausführen.

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 den Server hängen lässt: 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. Validieren Sie Anmeldeinformationen vor dem Erstellen des Transports.
  //    Ein fehlender Schlüssel muss sofort fehlschlagen — lassen Sie den Unterprozess 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 Sie sich über den stdio-Transport mit dem agentpay MCP-Server.
  // Whitelisten Sie nur die Umgebungsvariablen, die der Server benötigt — leiten Sie niemals den gesamten process.env
  // an einen Drittanbieter-Unterprozess 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. Legen Sie die Ausgabenrichtlinie vor der Delegation an den Agenten fest.
  //    Ü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(
      `Ausgabenrichtlinie konnte nicht festgelegt werden — Delegation wird verweigert: ${JSON.stringify(policyResult.content)}`
    );
  }

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

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

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

  // Pfad 3: Werkzeug 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 gab unerwartetes Format zurück — 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 Unteragenten weisen Sie über Ihre Orchestrierungsschicht eine SpendingPolicy zu. Geben Sie einem Agenten niemals unbegrenzte Ausgaben.
• Abhängigkeiten festlegen: Geben Sie in Ihrer MCP-Konfiguration immer eine genaue Version 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 Zahlungswerkzeug nicht erreichbar ist, blockieren Sie die kostenpflichtige Aktion — greifen Sie nicht auf ungemessenen Zugriff zurück.
• Mit security-review kombinieren: Zahlungswerkzeuge 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.

Produktionsreferenz

• npm: agentwallet-sdk
• In NVIDIA NeMo Agent Toolkit integriert: PR #17 — x402-Zahlungswerkzeug 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 Skill: okx/onchainos-skills
• OKX Payments Übersicht: web3.okx.com/onchainos/dev-docs/payments/overview