Für KI-Agenten

Agenten-Doku: MCP & Katalog-API

Zwei Wege zur Integration. Die Katalog-REST-API ist öffentlich und heute live - durchsuche Marken, Produkte und Stückelungen ohne jeden Zugangsschritt. Der MCP-Server ergänzt den Checkout: ein Agent erstellt eine Bestellung, bezahlt eine Lightning-Rechnung aus seiner eigenen Wallet und erhält einen Einmal-Anzeigelink mit dem Code. Kein Konto, keine hinterlegte Karte, keine Anmeldung.

1 · Katalog-REST-API (jetzt live)

Die Browsing-Endpunkte sind öffentlich und mit einem OpenAPI-Schema dokumentiert. Die MCP-Lese-Tools unten sind dünne Hüllen darüber, du kannst also direkt gegen die API bauen, wenn du lieber reines HTTP nutzt.

Referenz: api.giftcardshop.org/v1/docs (Schema unter /v1/openapi.json).

2 · MCP-Server (Frühzugang)

Der MCP-Server und der autonome Lightning-Checkout sind im Frühzugang. Die Lese-Tools funktionieren gegen die Live-API; create_order benötigt ein HMAC-Geheimnis, das wir bereitstellen, sobald du Kontakt aufnimmst. Die Integrationsform steht unten, damit du sie vorab einrichten kannst.

Remote (gehostet)

Richte einen beliebigen Streamable-HTTP-MCP-Client auf https://api.giftcardshop.org/mcp aus - nichts zu installieren. Die Browsing-Tools sind öffentlich; create_order und get_order_status brauchen ein Bearer-Token, im Frühzugang verfügbar, wenn du Kontakt aufnimmst.

{
  "mcpServers": {
    "giftcardshop": {
      "url": "https://api.giftcardshop.org/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Sende dein Token im Authorization-Header, wie oben gezeigt. Vollständiges OAuth 2.1 - für Schreibzugriff aus ChatGPT/Claude - ist auf der Roadmap.

Client-Konfiguration (stdio)

Der Server spricht MCP über stdio. Richte einen beliebigen MCP-Client (Claude Desktop und andere) darauf aus:

{
  "mcpServers": {
    "giftcardshop": {
      "command": "npx",
      "args": ["-y", "@giftcardshop/mcp"],
      "env": { "GCS_INTERNAL_SECRET": "<64-hex>" }
    }
  }
}

Ohne GCS_INTERNAL_SECRET funktionieren die Lese-Tools weiterhin und create_order meldet, dass es nicht konfiguriert ist.

Umgebung

Variable	Standard	Zweck
`GCS_API_BASE`	`https://api.giftcardshop.org`	Öffentliche API-Basis.
`GCS_INTERNAL_SECRET`	(nicht gesetzt)	64-Hex-HMAC-Geheimnis; aktiviert `create_order`. Nicht gesetzt = nur Lesen.

Tools

list_brandsreadGET /v1/brands

Listet die Geschenkkarten-Marken im Katalog auf.

`country`	`string?`	ISO-3166-1-alpha-2-Ländercode, z. B. US
`limit`	`number?`	1 bis 100
`offset`	`number?`	0 oder mehr (Paginierung)

search_productsreadGET /v1/products

Sucht oder listet kaufbare Produkte.

`q`	`string?`	Freitextsuche, z. B. "amazon"
`brand`	`string?`	Marken-Slug
`country`	`string?`	ISO-3166-1-alpha-2-Ländercode, z. B. AT
`amount`	`number?`	Nennwert / Stückelung, z. B. 5
`currency`	`string?`	ISO 4217, zusammen mit amount, z. B. EUR
`category`	`string?`	Kategorie-Slug
`limit`	`number?`	1 bis 100

get_productreadGET /v1/products/:id

Ein Produkt mit seinen Stückelungen/Varianten. Hier bekommst du die variantId, den Betrag und die Währung, die create_order braucht.

id string Produkt-id (erforderlich)

get_order_statusreadGET /v1/orders/:id

Zahlungsstatus einer Bestellung und ob der Einmal-Anzeigelink mit dem Code schon verfügbar ist.

orderId string erforderlich

create_orderwritePOST /internal/agent-orders (HMAC-signed)

Erstellt eine Bestellung und liefert eine Lightning-Rechnung zum Bezahlen. Benötigt die variantId, den Betrag und die Währung aus get_product.

`productId`	`string`	erforderlich
`variantId`	`string`	eine Stückelungs-id aus get_product
`amount`	`string`	Nennwert als Dezimal-String, z. B. "50"
`currency`	`string`	ISO 4217, z. B. EUR
`idempotencyKey`	`string`	eindeutiger Schlüssel (8+ Zeichen), damit ein erneuter Versuch nie doppelt belastet
`email`	`string?`	optional: den Anzeigelink auch an diese Adresse senden

Ein ? nach dem Typ bedeutet, dass der Parameter optional ist. Lese-Tools geben das API-JSON unverändert zurück.

Der Bestellablauf

Finde ein Produkt und lies seine Varianten mit get_product - notiere variantId, amount und currency.
Rufe create_order mit einem frischen idempotencyKey auf. Du bekommst eine Rechnung zurück:

{
  "orderId": "ord_...",
  "invoiceId": "inv_...",
  "invoiceUrl": "https://btcpay.../i/inv_...",
  "bolt11": "lnbc...",        // present once the invoice is minted
  "sats": 12345,              // amount in satoshis
  "total": "52.50",
  "currency": "EUR",
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

Bezahle die Lightning-Rechnung (bolt11 / invoiceUrl) aus deiner eigenen Wallet.
Frage get_order_status ab, bis sie bezahlt meldet und der Anzeigelink verfügbar ist.
Öffne den Einmal-Anzeigelink, um den Code zu lesen. Er ist einmal einsehbar.

Zahlung

Der Agent bezahlt eine Lightning-Rechnung aus seiner eigenen Wallet. Geschenkkarten-Codes sind nicht erstattungsfähig, und genau deshalb passt Lightning: sofortige Abwicklung, keine Rückbuchungen, keine Kartennetzwerke. Autonome Zahlung pro Aufruf (L402) ist auf der Roadmap.

Zugang erhalten

Möchtest du einen Agenten an den Checkout anbinden? Kontaktiere uns und wir richten dir den MCP-Server und ein HMAC-Geheimnis ein.

‹ Zurück zur Agenten-Übersicht