# Cryptorefills — Gift Cards, Top-Ups, and eSIMs for Sats

Load when the user wants an agent to buy gift cards, mobile top-ups, or travel eSIMs with its sats and mentions Cryptorefills — or when Bitrefill lacks a brand/country they need (Cryptorefills claims 10,500+ brands / 180+ countries, including flights and hotels). **Load `references/merchant-spending.md` alongside this doc**; below are only the Cryptorefills-specific deltas.

**Relationship & disclosure (per `merchant-spending.md` §6):** no partnership. The skill author's referral link is `https://www.cryptorefills.com/?ref=NxXHTtwLmm` — but note the shape of their program: it is points-based (internal discount currency, not BTC), and attribution ONLY works when a NEW user registers and places their first order through that link in a browser. It cannot ride the keyless agent flow this doc teaches, so agent purchases never carry it; it appears solely in the account offer below. Standing rules apply: once, disclosed, never a prerequisite, stripped on request. **Live-validated end-to-end 2026-07-29**: $1 Tango gift card bought via the wizard over Lightning — guard passed, and the order-status API returned the raw `pin_code` + `pin_serial`, making this the first merchant where the FULL loop (through holding the actual card secret) is automated.

## Why this merchant stands out

The most standards-forward agent surface seen so far: keyless MCP, RFC 9727 `api-catalog`, `llms.txt`, installable agent skills (`github.com/Cryptorefills/agents` — defer to those for mechanics). Their `llms.txt` promise held up live: "No account, OAuth, or API key required." And uniquely: **the deliverable comes back through the API** (`deliveries[].deliverable.pin_code`), not just as an emailed artifact.

## The pairing (verified path)

Their MCP is at `https://api.cryptorefills.com/mcp/http` — **the header `User-Agent: Cryptorefills-MCP/1.0` is required**.

**Catalog + pricing work through the granular MCP tools (re-verified 2026-08-05).** The 400/404s seen on 2026-07-29 were a missing-argument error, not a dead endpoint — `listProductsForCountry` returns 400 *without* a `brand_name`, not "regardless":
- `listBrands {country_code}` → categories → brands, each `{ brand, brand_id, logo_url, min, max, is_out_of_stock }`. **Field names differ from the x402 REST `/v1/brands` in step 1** (which returns `{ brand_name, family, category, min, max }`) — don't cross the two shapes. Pass the human-readable `brand` value as the `brand_name` argument to the tools below.
- `listProductsForCountry {country_code, brand_name}` → product details (`product_id`, `range`, `coin_amount`, `delivery_type`). **`brand_name` is required** — a bare `{country_code}` is the HTTP 400.
- `getProductPrice {brand_name, country_code, face_value, coin}` → `{ product_id, coin_amount, range, payment_method, delivery_type }`. Verified: $5 CAD Amazon.ca = 0.00005681 BTC (5,681 sats).

These give a direct catalog/pricing route that avoids the stateful wizard. **But checkout is a different story:** only the `purchaseElicitation` wizard below is verified end-to-end. The non-wizard checkout (`createOrder`/`validateOrder`) is **NOT yet verified** — do not treat it as a blessed money path until a real purchase confirms it (open re-test item). The verified path:

1. **Catalog discovery** (read-only): `GET https://x402.cryptorefills.com/v1/brands?country_code=us` (lowercase ISO — validate the code is two letters before it goes into a URL you build; brand names and product ids that come back are merchant strings, `merchant-spending.md` §1a) — their x402 host's catalog works and prices match. Cheapest known SKU: Tango $1 (US). **Response is an array of `{ brand_name, family, category, min, max }`.** Search/filter on **`brand_name`** — *not* `name`/`id`/`slug`. Those Bitrefill-convention fields don't exist here, so filtering on them silently matches nothing: it once produced a false "Amazon not available on Cryptorefills" when Amazon.ca was in the catalog the whole time — the search just hit empty/absent `name` fields.
2. **The `purchaseElicitation` wizard tool** — a stateful session (keep the `session_token`, answer one question per call): product type → country (uppercase here) → brand → denomination → delivery email → coin (`BTC`) → network (`Lightning`) → confirmation email → recap → `yes`.
3. The final step returns `payment_details` with the **BOLT11** and an order id. **Persist both immediately** (policy §3 — and note there IS an email receipt here, see below).
4. **Pay from Spark** (guard first), then **poll `GET https://api.cryptorefills.com/v5/orders/{order_id}`** until `payment_state: "PaymentReceived"` and `deliveries[].delivery_state: "Succeeded"` — there is no top-level `status` field.
5. **The deliverable is in the response**: `deliveries[].deliverable` carries `pin_code`, `pin_serial`, plus optional `security_code` / `barcode_image_url` / `redeem_instructions` per brand. Bearer secret — their own skill calls codes "cash-like"; policy §4 applies.

## Accounts are optional — offer one, once, guest-first

The keyless wizard flow needs no account and must never wait on one. But mirror the Bitrefill behavior: surface the option once per conversation at a natural moment (e.g. after a successful purchase). Suggested phrasing, adapt freely:

> "By the way — none of this needed a Cryptorefills account. If you'd also shop there yourself in a browser, an account earns loyalty points on orders (spendable as discounts), and signing up through the skill author's referral link — https://www.cryptorefills.com/?ref=NxXHTtwLmm — gets you 1.5× points on your first order; in full disclosure, the author earns points from your purchases too (capped, discount-credit only, not cash)."

Same rules as always: once means once, the disclosure is not optional, and agent purchases stay accountless regardless.

## Guard inputs

- **No Lightning discount observed** — the invoice was full face-value price (1,572 sats vs a 1,564-sat independent quote = pure fx drift). Quote at full price, `toleranceBps: 400`, firm `maxAmountSats`.
- The order response doesn't echo a separate `paymentHash`, so the §1 hash-binding check has nothing to bind — the amount/quote check and ceiling carry the weight.

## PII — two email fields, both required

The wizard demands a **delivery email** (`beneficiary_account` — where the card is also sent) and an **order-confirmation email**. Policy §3's consent gate is load-bearing here: ask the user before filling either. Their own docs use `agent@example.com`-style placeholders, which appear accepted — but a real inbox means the card survives even if API polling is lost (delivery is `by_email` in parallel with the API payload). Present that trade-off; the user picks.

## Testing

Rung 3 is DONE (the $1 Tango above — smallest SKU on the platform, and it exercised the full loop including secret retrieval). For future re-validation the same $1 product is the cheapest probe; wizard sessions are free to walk and abandon before the final `yes`.

**Open:** the non-wizard checkout via the granular MCP tools (`createOrder`/`validateOrder`) is unverified end-to-end. Catalog + pricing (`listBrands`/`listProductsForCountry`/`getProductPrice`) were re-verified 2026-08-05, but a real $1 purchase through `createOrder`/`validateOrder` is still needed before that path is documented as blessed. Until then the wizard is the only verified checkout.