{
  "name": "GiftPulse",
  "description": "Send a REAL mobile airtime top-up or order a REAL digital gift card, worldwide, via Reloadly. ACTION API, not a data lookup: paying causes airtime to be credited to a phone number or a gift card to be issued. Flow: free quote (confirm phone number/recipient with your human) -> paid send/order -> optional status poll. Pay-per-call via x402 on Base.",
  "url": "https://giftpulse.theaslangroupllc.com",
  "version": "1.0.0",
  "capabilities": [
    "send-airtime-topup",
    "mobile-operator-auto-detect",
    "order-digital-giftcard",
    "giftcard-catalog-search",
    "redemption-code-delivery",
    "delivery-status-reconciliation",
    "agentic-commerce-action",
    "physical-world-action"
  ],
  "target_users": [
    "Agents that need to send real airtime to a phone number as the outcome of a workflow (customer support credit, incentive, remittance top-up)",
    "Agents that need to issue a gift card (rewards, refunds-in-kind, promotions, employee/customer incentives)",
    "Consumer-facing shopping/concierge agents completing a gifting task on a user's behalf",
    "Business-automation agents distributing incentive value at scale, worldwide"
  ],
  "data_sources": [
    "Reloadly (reloadly.com) — Topups API (mobile airtime, 170+ countries) and Gift Cards API (300+ brands, 14,000+ products)"
  ],
  "payment": {
    "protocol": "x402",
    "network": "eip155:8453",
    "asset": "USDC",
    "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x50ab2018c06c6E4eAA9BA52057Eb55eD284912fc"
  },
  "endpoints": [
    {
      "path": "/api/health",
      "method": "GET",
      "description": "Liveness check + current mode (sandbox/live).",
      "price_usd": 0,
      "payment_required": false
    },
    {
      "path": "/api/topup/lookup",
      "method": "GET",
      "description": "Auto-detect the mobile operator for a phone number and return its live top-up amount range/denominations and current discount, before quoting or sending airtime.",
      "parameters": [
        { "name": "phone", "required": true, "description": "Full E.164 phone number" },
        { "name": "country_iso", "required": false, "description": "ISO-2 override for shared calling codes" }
      ],
      "price_usd": 0.01,
      "payment_required": true
    },
    {
      "path": "/api/topup/quote",
      "method": "POST",
      "description": "Free, exact price quote + signed quote_id for a prospective airtime top-up. Echoes the full phone number and resolved operator for human confirmation.",
      "parameters": [
        { "name": "phone", "required": true },
        { "name": "country_iso", "required": false },
        { "name": "operator_id", "required": false },
        { "name": "amount_usd", "required": true }
      ],
      "price_usd": 0,
      "payment_required": false
    },
    {
      "path": "/api/topup",
      "method": "POST",
      "description": "THE action: credits real airtime to a phone number once payment settles. Requires a verified quote_id and a client_request_id for idempotency. Price = amount_usd + $0.50; every order capped at $25.00.",
      "parameters": [
        { "name": "quote_id", "required": true },
        { "name": "issued_at", "required": true },
        { "name": "amount_micro", "required": true },
        { "name": "phone", "required": true },
        { "name": "country_iso", "required": true },
        { "name": "operator_id", "required": true },
        { "name": "amount_usd", "required": true },
        { "name": "client_request_id", "required": true }
      ],
      "price_usd_min": 0.54,
      "price_usd_max": 25.00,
      "payment_required": true
    },
    {
      "path": "/api/topup/{id}",
      "method": "GET",
      "description": "Cheap delivery status/reconciliation poll for a previously sent top-up.",
      "parameters": [ { "name": "id", "required": true } ],
      "price_usd": 0.005,
      "payment_required": true
    },
    {
      "path": "/api/giftcard/catalog",
      "method": "GET",
      "description": "Search Reloadly's gift card catalog (300+ brands, 14,000+ products/denominations).",
      "parameters": [
        { "name": "query", "required": false },
        { "name": "country", "required": false },
        { "name": "page", "required": false },
        { "name": "size", "required": false }
      ],
      "price_usd": 0.01,
      "payment_required": true
    },
    {
      "path": "/api/giftcard/quote",
      "method": "POST",
      "description": "Free, exact price quote + signed quote_id for a prospective gift card order.",
      "parameters": [
        { "name": "product_id", "required": true },
        { "name": "unit_price", "required": true },
        { "name": "quantity", "required": false },
        { "name": "recipient_email", "required": false }
      ],
      "price_usd": 0,
      "payment_required": false
    },
    {
      "path": "/api/giftcard",
      "method": "POST",
      "description": "THE action: issues a real gift card once payment settles, either emailed to recipient_email or returned as a redemption code directly in the response. Requires a verified quote_id and a client_request_id for idempotency. Price = unit_price x quantity; every order capped at $25.00.",
      "parameters": [
        { "name": "quote_id", "required": true },
        { "name": "issued_at", "required": true },
        { "name": "amount_micro", "required": true },
        { "name": "product_id", "required": true },
        { "name": "unit_price", "required": true },
        { "name": "quantity", "required": false },
        { "name": "recipient_email", "required": false },
        { "name": "client_request_id", "required": true }
      ],
      "price_usd_min": 0.01,
      "price_usd_max": 25.00,
      "payment_required": true
    },
    {
      "path": "/api/giftcard/{id}",
      "method": "GET",
      "description": "Cheap status poll and redemption-code re-fetch. Requires the client_request_id used at purchase, which gates access.",
      "parameters": [
        { "name": "id", "required": true },
        { "name": "client_request_id", "required": true }
      ],
      "price_usd": 0.005,
      "payment_required": true
    }
  ],
  "agent_workflow_examples": [
    "Send airtime: GET /api/topup/lookup?phone=... -> POST /api/topup/quote -> confirm phone+operator with human -> POST /api/topup -> GET /api/topup/{id}",
    "Order a gift card, code returned directly: GET /api/giftcard/catalog?query=Amazon -> POST /api/giftcard/quote -> POST /api/giftcard (no recipient_email) -> read redemption_code from the response",
    "Order a gift card, emailed to recipient: POST /api/giftcard/quote with recipient_email -> POST /api/giftcard with the same recipient_email"
  ],
  "key_facts": [
    "This is an ACTION API — paying causes real airtime or a real gift card to be issued, not a data return",
    "Every response carries mode: \"sandbox\" or \"live\" — sandbox mode is the default and delivers nothing real",
    "Always confirm the phone number (top-ups) or recipient (gift cards) with a human before paying — Reloadly does not refund a correct-but-wrong-intent send",
    "No refunds once Reloadly confirms delivery/issuance (matches Reloadly's own policy) — except for our error",
    "Every order is capped at $25.00 total",
    "client_request_id is required on every paid POST and doubles as Reloadly's own idempotency key — Reloadly hard-rejects a reused one, so GiftPulse's own store is what makes a retry safe"
  ],
  "openapi": "https://giftpulse.theaslangroupllc.com/openapi.json",
  "llms_txt": "https://giftpulse.theaslangroupllc.com/llms.txt",
  "contact": "https://giftpulse.theaslangroupllc.com"
}