Agent Gift Cards

What the service does

• Product catalog with search by brand, country, currency and category.
• Live price and availability check at the supplier for every quote.
• Binding quote with an expiry time (a few minutes). The quoted amount is the only amount accepted.
• Payment with x402 (USDC). The card is ordered only after the payment has settled.
• Code delivery in the response; the code can be fetched again with the private order token for 30 days.
• Order status, protection against double orders, and a refund process if a paid card cannot be delivered.

How agents use it

1. GET /api/v1/giftcards/products?country=DE: choose a product and a face value (free).
2. POST /api/v1/giftcards/quote with {"product_id","face_value"}: binding price in USDC and expiry (free).
3. Show the price to the person responsible and get an explicit approval of this one purchase.
4. POST /api/v1/giftcards/orders with {"quote_id"}: the first answer is HTTP 402 with the exact amount; an x402 client pays and repeats the call.
5. The answer contains the code, the order id and a private order_token. Store both. GET /api/v1/giftcards/orders/{id} with Authorization: Bearer <order_token> shows the order again.

Many x402 wallets refuse payments above 1 USD by default. Raise the spending limit for this one purchase only, and never give an agent more spending authority than the approved order.

How the x402 payment works

The order route answers HTTP 402 with a PAYMENT-REQUIRED header: amount (from the stored quote), asset USDC, network and recipient. The buyer signs a USDC transfer authorization (EIP-3009) and sends it in the PAYMENT-SIGNATURE header. Our server checks amount, recipient and signature, settles the payment on-chain first and only then orders the card. A payment for any other amount is refused before settlement. Repeating a request with the same payment never buys a second card.

Endpoints

GET  /api/v1/giftcards/catalog        free · brands, countries, currencies, categories
GET  /api/v1/giftcards/products       free · ?brand= &country= &currency= &category=
POST /api/v1/giftcards/quote          free · {"product_id","face_value"} -> quote_id, price, expires_at
POST /api/v1/giftcards/orders         x402 · {"quote_id"} -> code, order_id, order_token
GET  /api/v1/giftcards/orders/{id}    order token · status and code

Errors use {"error","message"}: 400 invalid input, 402 payment required, 404 unknown, 409 quote or payment already used, 410 quote expired, 422 invalid face value or order too large, 429 limit, 502 paid but not delivered (refund process), 503 switched off, paused or supplier unavailable. Details: OpenAPI.

Prices and fees

Price = our purchase cost at the supplier (converted to USD, rounded up) plus a service fee of 3.5 %, rounded up to whole cents. Example at 3.5 %: purchase cost 100.00 USD → 103.50 USDC. The quote shows the exact amount before you pay. There are no other fees from us; network fees of the payment are covered by the payment facilitator.

For developers

// Node.js with @x402/fetch (buyer side)
const pay = wrapFetchWithPayment(fetch, client); // client with a raised spend cap
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();
// keep order.order_id and order.order_token; never pay a second time if the outcome is unclear

For businesses only (B2B). If an order shows refund_pending or settlement_uncertain, do not pay again: we deliver or refund. Privacy and terms.