For AI agents

Agent docs: MCP & catalog API

Two ways to integrate. The catalog REST API is public and live today - browse brands, products and denominations with no access step. The MCP server adds checkout: an agent creates an order, pays a Lightning invoice from its own wallet, and receives a single-view reveal link with the code. No account, no card on file, no signup.

1 · Catalog REST API (live now)

The browsing endpoints are public and documented with an OpenAPI schema. The MCP read tools below are thin wrappers over them, so you can build directly against the API if you prefer plain HTTP.

Reference: api.giftcardshop.org/v1/docs (schema at /v1/openapi.json).

2 · MCP server (early access)

The MCP server and autonomous Lightning checkout are in early access. The read tools work against the live API; create_order needs an HMAC secret we provide once you get in touch. The integration shape is below so you can wire it up ahead of time.

Client config (stdio)

The server speaks MCP over stdio. Point any MCP client (Claude Desktop and others) at it:

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

Without GCS_INTERNAL_SECRET the read tools still work and create_order reports it is not configured.

Environment

Variable	Default	Purpose
`GCS_API_BASE`	`https://api.giftcardshop.org`	Public API base.
`GCS_INTERNAL_SECRET`	(unset)	64-hex HMAC secret; enables `create_order`. Unset = read-only.

Tools

list_brandsreadGET /v1/brands

List gift-card brands in the catalog.

`country`	`string?`	ISO 3166-1 alpha-2 country code, e.g. US
`limit`	`number?`	1 to 100
`offset`	`number?`	0 or more (pagination)

search_productsreadGET /v1/products

Search or list purchasable products.

`q`	`string?`	free-text search, e.g. "amazon"
`brand`	`string?`	brand slug
`country`	`string?`	ISO 3166-1 alpha-2 country code
`category`	`string?`	category slug
`limit`	`number?`	1 to 100

get_productreadGET /v1/products/:id

One product with its denominations/variants. This is where you get the variantId, amount and currency that create_order needs.

id string product id (required)

get_order_statusreadGET /v1/orders/:id

Payment state of an order, and whether the single-view reveal link with the code is available yet.

orderId string required

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

Create an order and get a Lightning invoice to pay. Needs the variantId, amount and currency from get_product.

`productId`	`string`	required
`variantId`	`string`	a denomination id from get_product
`amount`	`string`	face value as a decimal string, e.g. "50"
`currency`	`string`	ISO 4217, e.g. EUR
`idempotencyKey`	`string`	unique key (8+ chars) so a retry never double-charges
`email`	`string?`	optional: also send the reveal link to this address

A ? after the type means the parameter is optional. Read tools return the API JSON verbatim.

The order flow

Find a product and read its variants with get_product - note the variantId, amount and currency.
Call create_order with a fresh idempotencyKey. You get back an invoice:

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

Pay the Lightning invoice (bolt11 / invoiceUrl) from your own wallet.
Poll get_order_status until it reports paid and the reveal link is available.
Open the single-view reveal link to read the code. It can be viewed once.

Payment

The agent pays a Lightning invoice from its own wallet. Gift card codes are non-returnable, which is exactly why Lightning fits: instant settlement, no chargebacks, no card networks. Per-call autonomous payment (L402) is on the roadmap.

Get access

Want to connect an agent to checkout? Get in touch and we will set you up with the MCP server and an HMAC secret.

‹ Back to the agents overview