x-payment-info — Payment-Discovery in OpenAPI

Was ist x-payment-info?

x-payment-info ist eine OpenAPI-Erweiterung, die Agenten mitteilt, welche Endpoints Geld kosten und wie viel — bevor sie einen Request senden. Statt einen 402 auszulösen, um den Preis zu erfahren, können Agenten die OpenAPI-Spezifikation vorab lesen.

So funktioniert es

Füge die Erweiterung zu jeder kostenpflichtigen Operation in deiner /openapi.json hinzu:

{
  "paths": {
    "/api/v1/submit": {
      "post": {
        "x-payment-info": {
          "authMode": "payment-required",
          "protocols": [
            { "mpp": { "method": "tempo", "intent": "charge" } },
            { "mpp": { "method": "stripe", "intent": "charge" } },
            { "[x402](/kb/de/x402)": {} }
          ],
          "price": {
            "mode": "fixed",
            "amount": "0.50",
            "currency": "USD"
          }
        }
      }
    }
  }
}

Zentrale Konzepte

Beratend, nicht autoritativ: Die 402-Antwort ist immer die Quelle der Wahrheit. x-payment-info hilft Agenten beim Planen, aber Laufzeit-Challenges haben Vorrang.
Protokollunabhängig: Listet alle akzeptierten Zahlungsmethoden (Stripe, Tempo, x402), damit Agenten wählen können.
Preismodi: fixed (exakter Preis) oder dynamic (Min/Max-Spanne, z. B. für Gebote).
Cache-freundlich: Empfohlen ist Cache-Control: max-age=300 auf der OpenAPI-Spezifikation.

Warum das wichtig ist

Ohne x-payment-info müssen Agenten jeden Endpoint anfragen, um herauszufinden, ob er kostenpflichtig ist und was er kostet. Mit der Erweiterung können Agenten die Spezifikation einmal lesen und ihr Budget über mehrere API-Aufrufe hinweg planen.

Wie AgentGrade danach prüft

AgentGrade liest deine /openapi.json und prüft, ob irgendeine Operation eine x-payment-info-Erweiterung hat. Das ist ein optionaler Check in der OpenAPI-Scoring-Gruppe — er kann deinen Score verbessern, schadet aber nicht, wenn er fehlt.

Mehr erfahren

paymentauth.org spec — Entwurf der Payment-Discovery-Spezifikation