Pour les agents IA

Documentation pour agents : MCP et API catalogue

Deux façons d'intégrer. L'API REST du catalogue est publique et active dès aujourd'hui - parcourez marques, produits et dénominations sans aucune étape d'accès. Le serveur MCP ajoute le paiement : un agent crée une commande, paie une facture Lightning depuis son propre portefeuille et reçoit un lien à usage unique contenant le code. Sans compte, sans carte enregistrée, sans inscription.

1 · API REST du catalogue (active maintenant)

Les endpoints de navigation sont publics et documentés avec un schéma OpenAPI. Les outils de lecture MCP ci-dessous sont de fines surcouches au-dessus, vous pouvez donc construire directement contre l'API si vous préférez du HTTP simple.

Référence : api.giftcardshop.org/v1/docs (schéma sur /v1/openapi.json).

2 · Serveur MCP (accès anticipé)

Le serveur MCP et le paiement autonome via Lightning sont en accès anticipé. Les outils de lecture fonctionnent contre l'API active ; create_order nécessite un secret HMAC que nous fournissons une fois que vous nous contactez. La forme d'intégration est ci-dessous pour que vous puissiez la préparer à l'avance.

Distant (hébergé)

Pointez n'importe quel client MCP en Streamable HTTP vers https://api.giftcardshop.org/mcp - rien à installer. Les outils de navigation sont publics ; create_order et get_order_status nécessitent un jeton bearer, disponible en accès anticipé lorsque vous nous contactez.

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

Envoyez votre jeton dans l'en-tête Authorization, comme ci-dessus. L'OAuth 2.1 complet - pour l'accès en écriture de ChatGPT/Claude - est sur la feuille de route.

Configuration du client (stdio)

Le serveur communique en MCP via stdio. Pointez n'importe quel client MCP (Claude Desktop et autres) vers lui :

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

Sans GCS_INTERNAL_SECRET les outils de lecture fonctionnent toujours et create_order signale qu'il n'est pas configuré.

Environnement

Variable	Par défaut	Rôle
`GCS_API_BASE`	`https://api.giftcardshop.org`	Base de l'API publique.
`GCS_INTERNAL_SECRET`	(non défini)	Secret HMAC de 64 hex ; active `create_order`. Non défini = lecture seule.

Outils

list_brandsreadGET /v1/brands

Liste les marques de cartes cadeaux du catalogue.

`country`	`string?`	code pays ISO 3166-1 alpha-2, p. ex. US
`limit`	`number?`	de 1 à 100
`offset`	`number?`	0 ou plus (pagination)

search_productsreadGET /v1/products

Recherche ou liste les produits achetables.

`q`	`string?`	recherche en texte libre, p. ex. "amazon"
`brand`	`string?`	slug de marque
`country`	`string?`	code pays ISO 3166-1 alpha-2, p. ex. AT
`amount`	`number?`	dénomination / valeur faciale, p. ex. 5
`currency`	`string?`	ISO 4217, avec amount, p. ex. EUR
`category`	`string?`	slug de catégorie
`limit`	`number?`	de 1 à 100

get_productreadGET /v1/products/:id

Un produit avec ses dénominations/variantes. C'est ici que vous obtenez le variantId, le montant et la devise dont create_order a besoin.

id string id du produit (obligatoire)

get_order_statusreadGET /v1/orders/:id

État de paiement d'une commande, et si le lien à usage unique contenant le code est déjà disponible.

orderId string obligatoire

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

Crée une commande et obtient une facture Lightning à payer. Nécessite le variantId, le montant et la devise de get_product.

`productId`	`string`	obligatoire
`variantId`	`string`	un id de dénomination de get_product
`amount`	`string`	valeur faciale en chaîne décimale, p. ex. "50"
`currency`	`string`	ISO 4217, p. ex. EUR
`idempotencyKey`	`string`	clé unique (8+ caractères) pour qu'une nouvelle tentative ne facture jamais deux fois
`email`	`string?`	optionnel : envoyer aussi le lien de révélation à cette adresse

Un ? après le type signifie que le paramètre est optionnel. Les outils de lecture renvoient le JSON de l'API tel quel.

Le flux de commande

Trouvez un produit et lisez ses variantes avec get_product - notez le variantId, amount et currency.
Appelez create_order avec une nouvelle idempotencyKey. Vous récupérez une facture :

{
  "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"
}

Payez la facture Lightning (bolt11 / invoiceUrl) depuis votre propre portefeuille.
Interrogez get_order_status jusqu'à ce qu'elle indique payé et que le lien de révélation soit disponible.
Ouvrez le lien à usage unique pour lire le code. Il est consultable une seule fois.

Paiement

L'agent paie une facture Lightning depuis son propre portefeuille. Les codes de cartes cadeaux ne sont pas remboursables, et c'est exactement pourquoi Lightning convient : règlement instantané, pas de rétrofacturation, pas de réseaux de cartes. Le paiement autonome par appel (L402) est sur la feuille de route.

Obtenir l'accès

Vous voulez connecter un agent au paiement ? Contactez-nous et nous vous configurons le serveur MCP et un secret HMAC.

‹ Retour à l'aperçu des agents