# Cryptorefills x402 Gift Card & Top-Up Store
# AI agents: use the catalog API to browse products, then POST /v1/orders to purchase

# Authentication & Payment
# This service uses the x402 protocol (HTTP 402 Payment Required)
# Payment method: USDC on Base (network: eip155:8453)
# Discovery: registered on Bazaar (x402.org)

# Endpoints
# GET /v1/brands?country_code=us                              - Discover available brands for a country
# GET /v1/catalog?country_code=us&brand_name=Amazon.com       - Discover denominations for a brand
# POST /v1/orders                                             - Create order (x402 two-phase flow)
# GET /v1/orders/{order_id}                                   - Poll order status & voucher delivery

# Order Flow
# 1. GET /v1/brands?country_code=us — discover available brand names
# 2. GET /v1/catalog?country_code=us&brand_name=<brand> — get product_id, denomination_label, is_range, face_value_usd / min_value / max_value
# 3. POST /v1/orders with email, items[] (set product_value only when is_range=true) - receive 402 with PAYMENT-REQUIRED header
# 4. Sign USDC EIP-3009 authorization for amount in PAYMENT-REQUIRED
# 5. Re-POST /v1/orders with PAYMENT-SIGNATURE header - receive 200 with order receipt
# 6. Poll GET /v1/orders/{order_id} until status = "completed". Voucher fields (voucher_code, pin_serial, security_code, redeem_instructions, url) appear inside deliveries[] once delivery_state = "completed".

# Service
# Name: Cryptorefills Gift Card Store
# Operator: AtomicRails / CryptoRefills
# Support: support@cryptorefills.com
# Terms: https://cryptorefills.com/terms