# nadanada — VPNs, eSIMs, and Burner Numbers for Sats Load when the user wants an agent to buy an anonymous VPN, travel eSIM, or disposable/rental phone number with its sats, or mentions nadanada. **Load `references/merchant-spending.md` alongside this doc** — it carries the shared payment policy; below are only the nadanada-specific deltas. **Relationship & disclosure:** no partnership; independent guidance. VPN flow **live-validated end-to-end 2026-07-27** — two real purchases: the first (782 sats) burned its config to the one-shot completion trap documented below, the second (784 sats) ran the corrected procedure cleanly through guard → pay → config → status. **The VPN purchase endpoint has since moved (`/vpn/purchase` → `/vpn/request`) and the response is wrapped in `{ success, data }`; re-verified 2026-08-05 — see "The pairing."** eSIM flow live-validated same day (US 1GB/7d, 4,464 sats, guard matched within 1 sat, ICCID + install details delivered); phone flows still untested. **Referral disclosure (per `merchant-spending.md` §6):** the skill author's nadanada referral code is **`sparkbtcbot`** (their affiliate program pays 15% on VPN/phone and 5% on eSIM, in BTC). The purchase examples below include it as `refCode: "sparkbtcbot"`; the website link with attribution is `https://nadanada.me?ref=sparkbtcbot`. It changes nothing about price or flow, it is never a prerequisite, and if the user asks to strip it, strip it without argument. ## Why this merchant is agent-friendly (with caveats found live) No accounts anywhere, no API key, no OAuth, no cart: purchase endpoints return a bare BOLT11 keyed by `paymentHash`. But their docs oversell two things (verified 2026-07-27): the advertised **5% Lightning discount is applied inconsistently — eSIM yes, VPN no** (details in "Paying" below), and "idempotent completion" is **only true for eSIM — the VPN config call is strictly one-shot** (below). Defer to `nadanada.me/api/v2/documentation` for endpoint shapes, but trust the live findings here where they conflict. ## The pairing 1. **Create the checkout** (include `"refCode": "sparkbtcbot"` — see the disclosure above; omit it if the user asks). **The path is product-specific, and the VPN one changed — do not use `/purchase` blindly:** - **VPN → `POST /api/v2/vpn/request`** (verified 2026-08-05). The old `/api/v2/vpn/purchase` now returns a **404 HTML page (Next.js), not JSON** — following it is a hard block. - **eSIM → `POST /api/v2/esim/purchase`** — live-validated 2026-07-29 but **NOT re-verified since the VPN rename; re-probe before trusting** (nadanada may be migrating `purchase`→`request` across products). - **The response is WRAPPED, not flat:** `{ "success": true, "data": { checkoutId, paymentMethod, paymentHash, paymentRequest, price, expiresAt } }`. Read **`resp.data.paymentRequest`** — a bare `resp.paymentRequest` is `undefined`. `data.price` is the USD charged; `data.expiresAt` is the **payment window**, NOT the VPN's validity (that's in the config — see below). **Confirmed on BOTH VPN and eSIM responses (2026-08-05)** — every `/api/v2/*` endpoint wraps in `{ success, data }`, so read everything off `data`. - **Save `data.checkoutId` immediately** — it's the order-lookup handle (`nadanada.me/order`) if anything goes wrong. **There is NO email/receipt parameter anywhere in the API** (verified against their OpenAPI spec) — policy §3's no-receipt-channel rule applies in full: what you persist is the only record. - VPN quirk: the `duration` field is **the price-in-USD tag, not a number of days** — the 1-day $0.50 plan is `duration: 0.5` (valid values come from `/api/v2/vpn/countries` `durations[].duration`). Confirmed live: `duration: 1` is rejected (`Invalid duration…`), `0.5` accepted. 2. **Pay the BOLT11 from Spark** — guard first (below). 3. **Complete** — eSIM: `POST /api/v2/esim/complete` with `paymentHash` **or `checkoutId`** (either handle works — verified 2026-08-05; both return 402 while unpaid), documented idempotent. Write the raw response body to disk (`await res.text()`, mode 0600) **before** `JSON.parse`: the install QR / LPA code is a bearer secret delivered once, and a body that fails to parse must not take it with it. The saved file is the only record (no email). VPN: see the one-shot warning below. Catalog/pricing lookups are unauthenticated GETs; rental-phone tools (only — see phone note below) also live on a keyless MCP endpoint (`https://mcp.nadanada.me/mcp`). If you reach the v2 REST API with `curl` rather than their MCP, the product ids, country codes and order ids you splice into the URL or body are merchant-returned strings: validate (`^[A-Za-z0-9][A-Za-z0-9._-]*$` with no `..`, ISO country codes) and pass as argv / `--data @file`, never interpolated (`merchant-spending.md` §1a). ## Paying — guard first Use `payMerchantCheckout` from `references/merchant-spending.md` §1 with these nadanada inputs: - **The advertised 5% Lightning discount is applied PER PRODUCT (verified live 2026-07-27): NOT on VPN, YES on eSIM.** VPN: quote at full catalog price (the guard's first live block proved it — 782-sat invoice vs 743 discounted quote, 782 = exactly the undiscounted $0.50). eSIM: checkouts return `data.originalPrice`/`data.price` with the 5% applied — quote at `usdPrice × 0.95` (confirmed 2026-08-05: `originalPrice 2.99 → price 2.84`). Assume nothing for untested products; the guard will tell you. - **`expectedPaymentHash: resp.data.paymentHash`.** The checkout returns the invoice's hash next to it, so bind to it: a swapped invoice then fails even at the right amount. - **Fiat→sats conversion adds drift beyond the 2% default.** Use an independent rate (e.g. Coinbase spot — in one live check mempool.space and Coinbase agreed within 0.3%), `toleranceBps: 400`, and a firm `maxAmountSats` ceiling. ```javascript const check = checkInvoiceAgainstQuote({ amountSats, // decoded from the returned BOLT11 quotedSats: Math.round(usdPrice * satsPerUsd), // VPN: full price. eSIM: × 0.95 (see above) maxAmountSats: 15_000, toleranceBps: 400, // fx drift: two different USD/BTC rates in play }); ``` ## eSIM SKU namespaces — merchant FIXED this 2026-07-29 (re-verify before trusting) **History worth knowing, because it will recur:** on 2026-07-27 the entire advertised catalog (`fixed_*` names, from `/esim/portfolio`, `/esim/bundles`, and the website) was rejected by `/api/v2/esim/purchase`; only undocumented country-level `esim_*_V2` SKUs worked, and regional bundles were unbuyable. Reported to the merchant; they replied "already aware, now fixed." **Re-probed 2026-07-29 — mostly true:** advertised `fixed_*` names now purchase successfully, including regional ones (`fixed_1GB_7D_NORTHAMERICA` / `north-america` → $1.19, the deal that didn't exist two days earlier). The `esim_*_V2` names still work too, so both namespaces are live. **One discrepancy remained when checked:** the catalog advertises `fixed_1GB_7D_EUROPE` at $1.19, and purchasing that exact pair returns `bundle_slug_mismatch` (stable across repeat probes ~20s apart), while `fixed_2GB_15D_EUROPE` on the same slug succeeds. Do not assume that is an unfixed bug — it could be a rollout in progress, or that bundle being genuinely retired upstream with the catalog as the stale side. (Note also that the `esim_*_V2` *region* names are constructed by extrapolating the country pattern; they were never documented, so their failing is unremarkable rather than evidence of anything.) **The durable rule, whichever explanation holds:** treat every SKU observation here as a snapshot, not a spec — probe the exact pair before quoting a price. **So the operating rule stands regardless of who fixed what:** a catalog listing is not proof of purchasability at this merchant. Probe the exact `bundleName` + `slug` pair with a purchase request before quoting a price to the user (creating a checkout is free — unpaid invoices expire), and be ready for either namespace. ## VPN completion is ONE-SHOT — prepare before you pay `POST /api/v2/vpn/config` burns the payment on first success: a retry returns `409 CONFIG_ALREADY_GENERATED`, and it is NOT idempotent regardless of what the general docs imply. Learned by losing one $0.50 config to a client-side crash *after* the server had answered. Hard rules: - **Generate the WireGuard keypair and PSK BEFORE paying**, and persist them to disk first — the server never sees the private key (their real headline feature), so a lost local key = a dead config. Node's X25519 keys **cannot** be exported as raw (`export({ type: "raw" })` throws) — export DER and take the trailing 32 bytes: ```javascript import { generateKeyPairSync, randomBytes } from "node:crypto"; const { publicKey, privateKey } = generateKeyPairSync("x25519"); // WireGuard wants base64 32-byte keys; slice the raw key off the end of the DER. const publicKeyB64 = publicKey.export({ type: "spki", format: "der" }).subarray(-32).toString("base64"); const privateKeyB64 = privateKey.export({ type: "pkcs8", format: "der" }).subarray(-32).toString("base64"); const presharedKey = randomBytes(32).toString("base64"); // Send publicKeyB64 + presharedKey in the /vpn/request body (above). Keep // privateKeyB64 LOCAL and inject it into the returned config's empty // `PrivateKey = ` line before handing the file to wg-quick. ``` - **The public key and PSK go in the PURCHASE body, not just the config call.** The `POST /api/v2/vpn/request` body is (verified 2026-08-05): ```json { "country": "22", "duration": 0.5, "publicKey": "", "presharedKey": "", "refCode": "sparkbtcbot" } ``` `country` is nadanada's **internal numeric code** from `/api/v2/vpn/countries` (`code`, e.g. Canada = `"5"`), NOT the ISO code — ISO fails with `Invalid country code`. The same `paymentHash` + `country` + `publicKey` + `presharedKey` are then replayed to `POST /api/v2/vpn/config`. - The config response is the **raw WireGuard config as `text/plain`**, not JSON — do not `res.json()` it. Persist the body immediately, before any parsing that could throw. - **The returned config's `PrivateKey` field is EMPTY** — by design (the server never had it). It comes back as `PrivateKey = ` with nothing after it, and handing that straight to `wg-quick` fails with a valid-*looking* config. **You must inject your locally-generated private key** into the `[Interface]` block before the config is usable. The failure mode is confusing precisely because the file looks complete. - The config also carries metadata comments — notably **`# Valid until: ` is the VPN's expiry**, which is distinct from the checkout's `data.expiresAt` (that was only the payment window). Parse the comment, not `expiresAt`, if you want to tell the user when the VPN dies. (`# Location: 🇨🇭 Switzerland` is also included.) - If completion fails irrecoverably, `checkoutId` + `paymentHash` are what support (`info@nadanada.me`) will want. ## Other product notes - **Phone products split by surface (verified 2026-07-28):** the v2 API and the MCP tools are **rental numbers only** ($12/3 mo, `userId` + `userSecret` auth — the secret is returned ONCE on first purchase; persist it like a seed). The **$1.50 disposable numbers are website-checkout only** — no API/MCP surface exists despite their agent docs advertising the flow. **Disposables use HOLD invoices** — payment settles only when an SMS arrives (≤20 min), else auto-cancels and refunds. A long-pending payment is *normal, not stuck*: never retry-pay. Whether Spark's SSP tolerates a long-held HTLC remains **untested** — testable only by pasting a website-checkout invoice into the wallet, and stock is limited per country/service (observed fully sold out 2026-07-28), so don't promise users a number is available. - **eSIM**: data-only, 200+ countries; ICCID (`^89\d{16,18}$`) is the handle for status/top-ups; top-ups queue without losing remaining data. New-purchase AND top-up flows live-validated 2026-07-27/28 (top-up: `POST /esim/[iccid]/purchase` -> pay -> `/esim/[iccid]/complete`; complete returned 402 until the invoice settled then succeeded on retry, confirming eSIM completes are genuinely retryable; the new bundle queued behind the active one as documented). Top-up SKUs: both `esim_*_V2` and `esimc_*_V2` namespaces create checkouts — match the eSIM's existing bundle family; the 5% discount applies to top-ups too. - **The purchase response (`data`) echoes a `providerBundleName`** (e.g. `esimc_1GB_7D_JP_V2`) that differs from the `bundleName` you sent (e.g. `fixed_1GB_7D_JP`) — it's the internal provider SKU the catalog name maps to. When you hit a `bundle_slug_mismatch` (see the SKU section above), this field is the debugging handle for what the catalog name actually resolved to. - **ICCID status is unconfirmed.** `GET /api/v2/esim/` for an unknown/bad ICCID returned a **200 with an HTML "Back in a moment" page**, not JSON or a 404 — so a non-JSON 200 is NOT proof the ICCID is valid or the service is down; it's a catch-all. The real status/usage shape is still untested with a genuine ICCID; verify before relying on it. - Minor, undocumented but harmless: `/esim/portfolio` includes a `data.nadaworld` category alongside countries/regions (a separate product line), and bundle objects carry `speed`, `description`, `roamingEnabled`, and `unlimited` beyond the doc's field list — useful when choosing between bundles. - Refund semantics vary — apply policy §3 accordingly: rental numbers explicitly non-refundable; disposable numbers self-refund via hold invoice; eSIM/VPN treat as non-refundable (the VPN one-shot above makes that literal). - Deliverables under policy §4's bearer-secret rule: WireGuard configs, eSIM install QR/codes, phone-number dashboard URLs. - nadanada sells anonymity products. That is legitimate — but if a user's request combines them with concretely harmful intent (e.g. numbers for verification fraud at scale), decline the purchase, not just the conversation.