# GiftPulse API — Pricing

GiftPulse sends real airtime top-ups and orders real gift cards via x402 pay-per-call (USDC on
Base). Unlike a data API, this is a **quote → confirm → execute** flow: quoting is free, sending/
ordering is paid, and once Reloadly confirms delivery to the operator or gift card issuer it
cannot be refunded (see [/terms.html](/terms.html)).

| Endpoint | What it does | Price/call |
|---|---|---|
| `POST /api/topup/quote` | Signed price quote for a top-up — no send, no charge | **Free** |
| `POST /api/giftcard/quote` | Signed price quote for a gift card order — no order, no charge | **Free** |
| `GET /api/topup/lookup` | Auto-detect mobile operator + live amount range/discount | $0.01 |
| `GET /api/giftcard/catalog` | Search 300+ gift card brands / 14,000+ products | $0.01 |
| `GET /api/topup/{id}` | Delivery status / reconciliation poll | $0.005 |
| `GET /api/giftcard/{id}` | Order status + redemption code re-fetch | $0.005 |
| `POST /api/topup` | **Send the airtime** — the paid action | amount_usd + $0.50 |
| `POST /api/giftcard` | **Order the gift card** — the paid action | unit_price × quantity |
| `GET /api/health` | Liveness + current mode | Free |

## Airtime top-up pricing

Total price = the airtime face value you request (`amount_usd`) + a flat **$0.50** processing fee.
Reloadly's own per-operator commission (visible as `discount_pct` on the resolved operator) is a
separate margin credited to our wallet automatically — it is not added to your price.

## Gift card pricing

Total price = `unit_price × quantity`, with **no additional GiftPulse fee** in v1. Reloadly's own
per-brand `sender_fee`/`sender_fee_pct` (shown in the catalog response) is the margin mechanism
here; some brands carry zero built-in fee, in which case the order is priced at cost today.

**Hard cap:** every order is capped at **$25.00** total, enforced server-side before payment is
ever requested. This is a safety rail (`MAX_ORDER_USD`), not a purchasable tier.

## How payment works

1. `POST /api/topup/quote` or `POST /api/giftcard/quote` (free) — get back an exact price, a
   signed `quote_id`, and a 15-minute expiry. The top-up quote echoes the full phone number and
   resolved operator so you can confirm with your human before paying.
2. `POST /api/topup` or `POST /api/giftcard` (paid, x402) — resubmit the same order plus the
   `quote_id`/`issued_at` from step 1, a `client_request_id` (for idempotency), and pay the exact
   price quoted. Reloadly credits the airtime or issues the gift card; you get back a transaction
   id and (for gift cards without a `recipient_email`) the redemption code.
3. `GET /api/topup/{id}` or `GET /api/giftcard/{id}` ($0.005) — optional status/reconciliation
   poll any time after sending/ordering.

- Machine-readable spec: [/openapi.json](/openapi.json) · agent card: [/.well-known/agent.json](/.well-known/agent.json) · [/llms.txt](/llms.txt)
- Terms (accepted by paying): [/terms.html](/terms.html)
- Part of [PulseNetwork](https://pulse.theaslangroupllc.com) — The Aslan Group LLC · info@theaslangroupllc.com