Agent Gift Cards

Was der Dienst macht

• Produktkatalog mit Suche nach Marke, Land, Währung und Kategorie.
• Live-Preis und Verfügbarkeit beim Lieferanten für jedes Angebot.
• Verbindliches Angebot mit Ablaufzeit (wenige Minuten). Nur der angebotene Betrag wird angenommen.
• Bezahlung per x402 (USDC). Bestellt wird erst, wenn die Zahlung abgewickelt ist.
• Code-Auslieferung in der Antwort; mit dem privaten Bestell-Token 30 Tage lang erneut abrufbar.
• Bestellstatus, Schutz vor Doppelbestellungen und ein Erstattungsablauf, falls ein bezahlter Gutschein nicht geliefert werden kann.

So nutzen KI-Agenten den Dienst

1. GET /api/v1/giftcards/products?country=DE: Produkt und Nennwert wählen (kostenlos).
2. POST /api/v1/giftcards/quote mit {"product_id","face_value"}: verbindlicher Preis in USDC mit Ablaufzeit (kostenlos).
3. Den Preis der verantwortlichen Person zeigen und genau diesen einen Kauf ausdrücklich freigeben lassen.
4. POST /api/v1/giftcards/orders mit {"quote_id"}: Die erste Antwort ist HTTP 402 mit dem genauen Betrag; ein x402-Client bezahlt und wiederholt den Aufruf.
5. Die Antwort enthält den Code, die Bestell-ID und ein privates order_token. Beides aufbewahren. GET /api/v1/giftcards/orders/{id} mit Authorization: Bearer <order_token> zeigt die Bestellung erneut.

Viele x402-Wallets lehnen Zahlungen über 1 USD standardmäßig ab. Das Ausgabelimit nur für diesen einen Kauf erhöhen und einem Agenten nie mehr Zahlungsvollmacht geben als für die freigegebene Bestellung.

So funktioniert die x402-Zahlung

Die Bestellroute antwortet mit HTTP 402 und einem PAYMENT-REQUIRED-Header: Betrag (aus dem gespeicherten Angebot), Währung USDC, Netzwerk und Empfänger. Der Käufer unterschreibt eine USDC-Überweisungsfreigabe (EIP-3009) und sendet sie im PAYMENT-SIGNATURE-Header. Unser Server prüft Betrag, Empfänger und Signatur, wickelt die Zahlung zuerst on-chain ab und bestellt erst danach den Gutschein. Eine Zahlung über einen anderen Betrag wird vor der Abwicklung abgelehnt. Eine Wiederholung mit derselben Zahlung kauft nie einen zweiten Gutschein.

Endpunkte

GET  /api/v1/giftcards/catalog        kostenlos · Marken, Länder, Währungen, Kategorien
GET  /api/v1/giftcards/products       kostenlos · ?brand= &country= &currency= &category=
POST /api/v1/giftcards/quote          kostenlos · {"product_id","face_value"} -> quote_id, Preis, expires_at
POST /api/v1/giftcards/orders         x402 · {"quote_id"} -> Code, order_id, order_token
GET  /api/v1/giftcards/orders/{id}    Bestell-Token · Status und Code

Fehler im Format {"error","message"}: 400 ungültige Eingabe, 402 Zahlung nötig, 404 unbekannt, 409 Angebot oder Zahlung schon verwendet, 410 Angebot abgelaufen, 422 ungültiger Nennwert oder Bestellung zu groß, 429 Limit, 502 bezahlt aber nicht geliefert (Erstattungsablauf), 503 ausgeschaltet, pausiert oder Lieferant nicht erreichbar. Details: OpenAPI.

Preise und Gebühren

Preis = unser Einkaufspreis beim Lieferanten (in USD umgerechnet, aufgerundet) plus eine Servicegebühr von 3,5 %, aufgerundet auf volle Cent. Beispiel bei 3,5 %: Einkaufspreis 100,00 USD → 103,50 USDC. Das Angebot zeigt den genauen Betrag vor der Zahlung. Weitere Gebühren von uns gibt es nicht; die Netzwerkgebühren der Zahlung trägt der Zahlungsabwickler.

Für Entwickler

// Node.js mit @x402/fetch (Käuferseite)
const pay = wrapFetchWithPayment(fetch, client); // Client mit erhöhtem Ausgabelimit
const quote = await (await fetch(BASE + "/api/v1/giftcards/quote", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ product_id, face_value: "25.00" }) })).json();
const order = await (await pay(BASE + "/api/v1/giftcards/orders", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ quote_id: quote.quote_id }) })).json();
// order.order_id und order.order_token aufbewahren; bei unklarem Ausgang nie erneut bezahlen

Nur für Unternehmen (B2B). Zeigt eine Bestellung refund_pending oder settlement_uncertain, nicht erneut bezahlen: Wir liefern oder erstatten. Datenschutz und Bedingungen.