@kaleidorg/mind 0.0.1 → 0.1.0

package/skills/bitrefill/references/browse.md

@@ -0,0 +1,71 @@
+# Path: Browse the Website
+
+Use when: user wants to **explore** Bitrefill (compare prices, learn product types, check denominations, see country availability) AND your runtime has a **residential-IP browser**. Browse-only by default — for purchases prefer [mcp.md](mcp.md).
+
+## Hard requirement: residential IP
+
+`www.bitrefill.com` sits behind Cloudflare. **Datacenter egress = 403.** Do NOT use Firecrawl, raw `fetch`, `curl`, or any scraping API.
+
+Viable runtimes:
+
+- **ChatGPT Atlas** — built-in residential Chromium.
+- **Cursor** — built-in browser tool runs from user's machine.
+- **Claude Code / Desktop / Cowork + Claude-for-Chrome** extension drives local Chrome.
+- **Any host + Playwright/Chrome MCP** running on user's machine.
+- **OpenClaw Gateway on user's host** — `browser` tool uses host IP. (See [host-openclaw.md](host-openclaw.md).)
+
+Not viable: ChatGPT web/Agent (OpenAI datacenter), Gemini consumer (Google datacenter), Jules (Google VM), any cloud sandbox without residential proxy.
+
+## URL patterns
+
+First path segment = **country** (Alpha-2 lowercase). Second = **language**.
+
+- Gift cards listing: `https://www.bitrefill.com/{country}/{lang}/gift-cards/`
+- Gift card category: `https://www.bitrefill.com/{country}/{lang}/gift-cards/{category-slug}/` (e.g. `/us/en/gift-cards/food/`)
+- Gift card product: `https://www.bitrefill.com/{country}/{lang}/gift-cards/{product-slug}/`
+- Direct search: `https://www.bitrefill.com/{country}/{lang}/gift-cards/?q={query}` (covers gift cards + top-ups + eSIMs; in-country prioritized)
+- Mobile top-ups: `https://www.bitrefill.com/refill/`
+- eSIMs (locale): `https://www.bitrefill.com/{country}/{lang}/esims/`
+- eSIMs (browse all destinations): `https://www.bitrefill.com/esim/all-destinations`
+- Single eSIM: `https://www.bitrefill.com/{country}/{lang}/esims/bitrefill-esim-{destination-slug}/` (e.g. `bitrefill-esim-japan`, `bitrefill-esim-global`)
+- Auth (no locale prefix): `/login`, `/signup`
+
+## Country in URL vs geolock
+
+- **URL country** filters which inventory is **listed**.
+- **Geolock** is enforced at **IP level** at checkout. A product may appear in listing but be unpurchasable if user's IP is outside allowed region.
+
+Match URL country to recipient's country to surface usable cards.
+
+## Listing filters & sort (gift cards)
+
+Query params on any gift-card listing (`/{country}/{lang}/gift-cards/[category/]`):
+
+- `redemptionMethod` — `online` | `instore`
+- `minRating` — `2` | `3` | `4` | `5`
+- `minRewards` — `1`–`10` (cashback %)
+- `s` — sort: `2` = A–Z, `3` = recently added, `4` = cashback. Default = popularity.
+
+Example: `https://www.bitrefill.com/us/en/gift-cards/food/?minRating=5&minRewards=4&redemptionMethod=instore`
+
+## Categories (popular slugs)
+
+`top-products`, `retail`, `apparel`, `electronics`, `food`, `restaurants`, `food-delivery`, `streaming`, `games`, `travel`, `flights`, `accommodation`, `entertainment`, `gasoline`, `vpn`, `multi-brand`, `digital-wallet`, `groceries`, `pharmacy`, `experiences`, `gifts`. Full list: <https://docs.bitrefill.com/docs/Products>.
+
+## Suggested flow
+
+1. Clarify product type (gift card / top-up / eSIM) + country (+ carrier for top-ups).
+2. Send user to direct search URL or category path.
+3. For top-ups: country → carrier → amount.
+4. For eSIMs: destination → data + duration.
+5. Remind user to check denomination matches recipient's needs and that geolock applies at checkout.
+
+## Purchase from the browser?
+
+Possible but slow and risky. Anti-bot may block agent on brand redemption sites. Prefer [mcp.md](mcp.md) or [cli.md](cli.md) for purchases. If browser checkout is the only option, follow [safeguards.md](safeguards.md) — confirm with user, log invoice ID, treat redemption code as cash.
+
+## Source of truth
+
+- <https://www.bitrefill.com>
+- <https://help.bitrefill.com>
+- <https://docs.bitrefill.com/docs/Products>

package/skills/bitrefill/references/capability-matrix.md

@@ -0,0 +1,115 @@
+# Capability Matrix
+
+Per-host cheat sheet. Each entry = viable paths in priority order + one-line reason. Pick the first that fits, fall back as needed.
+
+Legend:
+
+- **MCP** → [mcp.md](mcp.md)
+- **CLI** → [cli.md](cli.md) (≥ 0.3.0: `login`/`verify`, not API key)
+- **API** → [api.md](api.md)
+- **Browse** → [browse.md](browse.md) (residential IP required)
+- **OpenClaw** → [host-openclaw.md](host-openclaw.md)
+
+## Anthropic
+
+### Claude.ai web — Free
+
+- No MCP custom URLs (Pro+ only). No shell. No residential browser.
+- **Path**: none viable for purchases. For browse: only if user installs Claude-for-Chrome extension → Browse.
+- **Fallback**: send user `bitrefill.com` link.
+
+### Claude.ai web — Pro / Max / Team / Enterprise / Cowork
+
+- MCP custom URLs allowed. Cowork adds desktop shell.
+- **Paths**: MCP first → Browse via Claude-for-Chrome ext.
+- Cowork only: + CLI via desktop shell.
+
+### Claude Desktop
+
+- MCP first-class (stdio + remote). No native shell, no native FS, no native HTTP — wire via MCP servers.
+- **Paths**: MCP first → CLI via stdio MCP wrapping `npx @bitrefill/cli` → Browse via Chrome ext or Computer Use.
+
+### Claude Code (CLI)
+
+- Most flexible. Full host shell, MCP, WebFetch, Chrome ext.
+- **Paths**: MCP first → CLI second → API via WebFetch / curl → Browse via Chrome ext or browser-use skill.
+- Tighten: sandbox allowlist `api.bitrefill.com`, `registry.npmjs.org`. Deny `~/.ssh`, `.env`.
+
+## OpenAI
+
+### ChatGPT web — Free
+
+- No custom MCP, no shell, datacenter browser → Cloudflare 403.
+- **Path**: none. Send user `bitrefill.com` link.
+
+### ChatGPT web — Plus / Pro / Business / Enterprise / Edu
+
+- Custom MCP via Apps & Connectors (Developer Mode for write tools). Code Interpreter has no network.
+- **Path**: MCP only. Browser is OpenAI datacenter — **do NOT route to Browse** (Cloudflare).
+
+### ChatGPT Desktop
+
+- Same as ChatGPT web. "Work with Apps" can read IDE/terminal panes but not execute.
+- **Path**: MCP only.
+
+### ChatGPT Atlas
+
+- Built-in Chromium with **residential IP** (user's network). Inherits account connectors. No shell.
+- **Paths**: Browse first (its superpower) → MCP via account connectors.
+
+### ChatGPT Agent (formerly Operator)
+
+- Sandboxed Linux + code interpreter. Hosted browser uses **OpenAI datacenter IP**.
+- **Paths**: MCP via account connectors → CLI inside sandbox shell → API via curl. **Do NOT route to Browse** (Cloudflare).
+
+### OpenAI Codex CLI
+
+- Full host shell (Seatbelt/Landlock sandboxable). MCP stdio + HTTP. Profiles in `config.toml`.
+- **Paths**: MCP first → CLI second → API via curl. Browser via MCP only.
+- Tighten: `--sandbox workspace-write --ask-for-approval on-request`. API key in profile, not committed config.
+
+## Google
+
+### Gemini consumer — Free
+
+- No MCP. No shell. No residential browser.
+- **Path**: none. Send user `bitrefill.com` link.
+
+### Gemini consumer — AI Pro / Ultra (US)
+
+- "Auto Browse" runs from Google IPs → likely Cloudflare-blocked on bitrefill.com.
+- **Path**: try Auto Browse + bitrefill.com URL; if blocked, send user the link.
+
+### Gemini CLI
+
+- Full host shell (sandboxable: Seatbelt / Docker / gVisor). MCP stdio + SSE + streamable-http.
+- **Paths**: MCP first → CLI second → API via `web_fetch` or curl. Browser via MCP (Chrome DevTools / Playwright).
+
+### Jules (async coding agent)
+
+- Ephemeral Ubuntu VM, Google IPs, no MCP exposed to user, no residential browser.
+- **Paths**: CLI inside VM → API via curl. **Not interactive** — best for batch tasks. No purchases recommended.
+
+## Other
+
+### Cursor IDE
+
+- Built-in browser tool, terminal tool, MCP (40-tool cap across servers). Cloud Agents in isolated VM.
+- **Paths**: MCP first → CLI in terminal → API via shell or built-in browser → Browse via built-in browser.
+- Tighten: keep `buy-products` out of `autoApprove` in `.cursor/mcp.json`.
+
+### OpenCode (sst/opencode)
+
+- Full host shell. MCP stdio + HTTP. Permission model per agent (`allow`/`ask`/`deny`).
+- **Paths**: MCP first → CLI second → API via `webfetch` or shell. Browser via MCP.
+
+### OpenClaw — superset host
+
+- Agentskills.io loader. MCP via `openclaw mcp set`. Full host shell + FS. `browser` tool uses host IP. Mobile nodes (camera, canvas, voice). Cron. Multi-channel chat (Telegram, WhatsApp, Slack, Discord, iMessage, Signal, Matrix, Teams, etc.).
+- **Paths**: read [host-openclaw.md](host-openclaw.md) **first**. **Guest CLI via `exec`** (preferred) → signed-in CLI (`balance`, cashback) → MCP → API → Browse.
+- Default agent: **Pi** (Anthropic / OpenAI / Google compatible via API key).
+- Unique scenarios: chat-channel purchase from phone, cron auto-renew top-ups, mobile camera OCR of receipts, multi-channel handoff.
+
+## Quick decision
+
+If user says "what host am I in?": run `command -v openclaw` and check `~/.openclaw/`. OpenClaw → guest CLI first. Else: MCP first (most hosts), fall back to CLI, then API.

package/skills/bitrefill/references/cli-headless-auth.md

@@ -0,0 +1,133 @@
+# Headless CLI auth (agents)
+
+Use when: agent must **sign up / sign in** without human at keyboard — unlock `balance`, cashback, order history.
+
+**Guest checkout needs no inbox** — pass `--email` on `buy-products` and pay crypto. Fastest first try; see [cli.md](cli.md) § Guest checkout.
+
+Use this doc when graduating guest → signed-in account with AgentMail or equivalent inbox.
+
+Requires `@bitrefill/cli` ≥ 0.3.0. Agent-owned inbox via **AgentMail or equivalent** — any provider with programmatic receive (list messages, parse body).
+
+## Why AgentMail or equivalent
+
+Bitrefill `login` sends magic-link code to email. Agent needs inbox API or MCP to poll/read messages without human. [AgentMail](https://www.agentmail.to/) is the reference implementation below; equivalent = Gmail API, IMAP, Mailgun inbound, etc. if your runtime already has access.
+
+## One-time inbox setup (AgentMail example)
+
+Human verifies provider account once. Agent handles Bitrefill after. Substitute your equivalent provider's sign-up + list/receive commands.
+
+```bash
+npm install -g agentmail-cli
+
+agentmail agent sign-up \
+  --human-email you@example.com \
+  --username bitrefill-agent
+# → api_key, inbox_id (e.g. bitrefill-agent@agentmail.to)
+
+export AGENTMAIL_API_KEY="am_..."   # from sign-up response
+
+agentmail agent verify --otp-code 123456   # human reads OTP from you@example.com
+```
+
+Official refs: [quickstart](https://docs.agentmail.to/quickstart.md), [agent onboarding](https://docs.agentmail.to/agent-onboarding.md).
+
+Optional (AgentMail): [AgentMail MCP](https://docs.agentmail.to/agent-onboarding.md) (`npx -y agentmail-mcp`) with `AGENTMAIL_API_KEY` — tools `list_threads`, `get_thread`, `get_message`. Equivalent providers: use their MCP/API instead.
+
+## Bitrefill auth flow
+
+Use agent inbox address as Bitrefill email (`inbox_id` from AgentMail or equivalent). Signup = login (same command).
+
+```bash
+npm install -g @bitrefill/cli
+
+bitrefill init --openclaw    # optional
+
+bitrefill login --email bitrefill-agent@agentmail.to
+```
+
+Poll inbox for Bitrefill verification email. AgentMail ([official list command](https://docs.agentmail.to/messages)):
+
+```bash
+agentmail inboxes:messages list --inbox-id bitrefill-agent@agentmail.to
+```
+
+Parse `extracted_text` or `text` from latest message for numeric code. Then:
+
+```bash
+bitrefill verify --code 123456
+```
+
+If Bitrefill account has TOTP, add `--otp` ([1Password](#totp-via-1password) below).
+
+Confirm:
+
+```bash
+bitrefill whoami --json
+# → { "identity": "registered", "email": "bitrefill-agent@agentmail.to", ... }
+```
+
+Then run catalog/purchase commands per [cli.md](cli.md).
+
+## End-to-end script sketch
+
+```bash
+INBOX="bitrefill-agent@agentmail.to"
+
+bitrefill login --email "$INBOX"
+sleep 5   # allow delivery
+
+CODE=$(agentmail inboxes:messages list --inbox-id "$INBOX" \
+  | jq -r '.messages[0].extracted_text // .messages[0].text' \
+  | grep -oE '[0-9]{6,8}' | head -1)
+
+bitrefill verify --code "$CODE"
+bitrefill whoami --json
+```
+
+Adjust regex/poll loop for your environment. Codes expire (~12–20 min server-side); on expiry re-run `login`.
+
+## TOTP via 1Password
+
+When Bitrefill account has authenticator enrolled, pass TOTP on verify.
+
+Secret reference ([official `op read`](https://www.1password.dev/cli/reference/commands/read)):
+
+```bash
+bitrefill verify --code "$CODE" \
+  --otp "$(op read 'op://Vault/Bitrefill/one-time password?attribute=otp')"
+```
+
+Item flag ([official `op item get --otp`](https://developer.1password.com/llms-cli.txt)):
+
+```bash
+bitrefill verify --code "$CODE" --otp "$(op item get Bitrefill --otp)"
+```
+
+Requires 1Password desktop app integration or service account. See [Get started with 1Password CLI](https://www.1password.dev/cli/get-started).
+
+## Safeguards
+
+- Dedicated low-balance Bitrefill account tied to agent inbox — not human primary email.
+- Agent inbox (AgentMail or equivalent) = auth surface; restrict who can read it.
+- `bitrefill reset` + re-login to rotate after compromise.
+- Never log magic-link codes or redemption codes to shared transcripts.
+
+Spending policy → [safeguards.md](safeguards.md).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `Access token is required for login/verify` | Run any CLI command first (MCP connect mints token), or `bitrefill reset` then retry |
+| `No pending login` | Re-run `login --email` before `verify` |
+| Code invalid / expired | Re-run `login --email`; poll inbox again |
+| `browser_url` in login response | Passkey/WebAuthn — human opens URL, then retry |
+| Inbox empty after login | Wait + re-list; check spam; confirm inbox address matches provider setup |
+
+More CLI errors → [troubleshooting.md](troubleshooting.md).
+
+## Source of truth
+
+- AgentMail (reference): <https://docs.agentmail.to/quickstart.md>, <https://docs.agentmail.to/messages>
+- Bitrefill CLI: <https://github.com/bitrefill/cli> (≥ 0.3.0)
+- 1Password CLI: <https://www.1password.dev/cli/reference/commands/read>

package/skills/bitrefill/references/cli.md

@@ -0,0 +1,237 @@
+# Path: CLI
+
+Use when: shell + `npm install` available, **host has no MCP client** (CLI talks to Bitrefill MCP under the hood). Runtimes: Claude Code, Codex CLI, Cursor terminal, Gemini CLI, OpenCode, OpenClaw, Jules (ephemeral VM), ChatGPT Agent (sandbox).
+
+Requires **`@bitrefill/cli` ≥ 0.3.0**. Sandboxed shells must allowlist `registry.npmjs.org` and `api.bitrefill.com`.
+
+## Install
+
+```bash
+npm install -g @bitrefill/cli
+```
+
+From source: `git clone https://github.com/bitrefill/cli.git && cd cli && pnpm install && pnpm build && npm link`.
+
+## Guest checkout (fastest first try)
+
+**No `login` / `verify`.** Works while `whoami` shows `identity: unregistered`. Fastest path for autonomous agents to try Bitrefill — search, quote, create invoice, pay crypto or open payment link.
+
+```bash
+bitrefill search-products --query "Amazon" --country IT
+bitrefill get-product-details --product_id "amazon_it-italy"
+
+bitrefill buy-products \
+  --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \
+  --payment_method lightning \
+  --return_payment_link true \
+  --email "agent@example.com"
+```
+
+Response: `invoice_id`, `payment_link`, optional `x402_payment_url` / Lightning invoice. Poll `get-invoice-by-id --invoice_id <uuid>`. Receipt goes to `--email`. Invoice expires in ~30 minutes.
+
+Guest payment methods: crypto (`lightning`, `usdc_base`, `bitcoin`, …) or `--return_payment_link true` (human/browser checkout, x402). **`balance` and `cashback` require a signed-in account** (below).
+
+## Sign up / sign in (balance, cashback, order history)
+
+After guest try, sign in when human wants **managed agent spending** or **rewards**:
+
+| Signed-in benefit | Why |
+|-------------------|-----|
+| **`--payment_method balance`** | Instant pay from store credit human pre-funds — natural spending cap, no on-chain wait |
+| **`--payment_method cashback`** | Pay from accumulated rewards balance (BTC) |
+| **Cashback on purchases** | Eligible products earn rewards back to account |
+| **`list-orders` / `list-invoices`** | Full order history + redemption codes in one place |
+
+Same `login` for new + existing accounts. Headless inbox → [cli-headless-auth.md](cli-headless-auth.md).
+
+```bash
+bitrefill login --email you@example.com
+bitrefill verify --code GGWK87DR              # email magic-link code
+bitrefill verify --code GGWK87DR --otp 122407   # + TOTP when account has 2FA
+bitrefill whoami --json
+
+# signed-in buy — instant from balance
+bitrefill buy-products \
+  --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \
+  --payment_method balance \
+  --email "you@example.com"
+```
+
+**Verify gotchas** (from real agent sessions):
+
+- Email code → `verify --code <value>`, **not** `login --code` (unknown option).
+- `--otp` = **authenticator TOTP only** when account has 2FA — not the email code. Need both `--code` and `--otp` when enrolled.
+- After sign-in, `login` disappears from `--help`; run `logout` first to switch accounts or sign up another email.
+
+## Bootstrap (optional)
+
+```bash
+bitrefill init                    # optional OpenClaw wiring only
+```
+
+`init` no longer stores API keys. OpenClaw only: merges MCP config + generates `~/.openclaw/skills/bitrefill/SKILL.md`.
+
+## Auth
+
+CLI 0.3.0: **guest checkout needs no sign-in.** Account auth = OAuth client_credentials (automatic on first MCP connect) + email magic-link. No `--api-key`, no `credentials.json`.
+
+| Step | Command | Notes |
+|------|---------|-------|
+| Register client | any command (or `login`) | MCP connect mints `access_token`; stored in `~/.config/bitrefill-cli/<host>.v1.json` |
+| Sign up or sign in | `login --email <addr>` | same command for new + existing accounts |
+| Complete auth | `verify --code <code> [--otp <totp>]` | code from email; `--otp` when account has TOTP |
+| Check session | `whoami [--json]` | `identity: registered` + `email` when signed in |
+| Sign out | `logout` | revokes session; keeps `client_id` |
+| Full reset | `reset` | clears all local state + revokes session |
+
+**TOTP via 1Password** ([official `op read`](https://www.1password.dev/cli/reference/commands/read)):
+
+```bash
+bitrefill verify --code "$CODE" --otp "$(op read 'op://Vault/Bitrefill/one-time password?attribute=otp')"
+```
+
+Shorthand ([official `op item get --otp`](https://developer.1password.com/llms-cli.txt)):
+
+```bash
+bitrefill verify --code "$CODE" --otp "$(op item get Bitrefill --otp)"
+```
+
+Server may return `browser_url` for passkey/WebAuthn — open in browser, then retry.
+
+**Developer API keys** (Personal REST / key-in-path MCP) are separate from CLI auth. See [mcp.md](mcp.md) and [api.md](api.md).
+
+## Global flags
+
+Place **before** the subcommand:
+
+- **`--json`** — stdout is a single JSON value per run (TOON decoded to JSON); status/errors on **stderr**. Use with `jq`.
+
+```bash
+bitrefill --json search-products --query "Amazon" --per_page 1 | jq '.products[0].name'
+```
+
+## Agent discovery
+
+`manifest` emits JSON schema for every built-in + MCP command:
+
+```bash
+bitrefill manifest --json | jq '.commands[].name'
+bitrefill manifest -o bitrefill-manifest.json
+```
+
+`llm-context` embeds the same manifest in a fenced JSON block.
+
+## `llm-context`
+
+Regenerates Markdown from live MCP `tools/list` (params, JSON Schema, example invocations). Use for **CLAUDE.md**, Cursor rules, or **`.github/copilot-instructions.md`**. Connection line shows redacted MCP URL — safe to commit.
+
+```bash
+bitrefill llm-context -o BITREFILL-MCP.md
+```
+
+## OpenClaw quick-bootstrap
+
+Optional `bitrefill init --openclaw`: merges MCP stub into `~/.openclaw/openclaw.json` + emits skill SKILL.md. **Not required for guest CLI** — install CLI and run guest checkout directly via `exec`. OpenClaw prefers guest CLI first; see [host-openclaw.md](host-openclaw.md). Hardening → exec-approvals for `bitrefill buy-products`.
+
+## Workflow
+
+Subcommands discovered from remote MCP (`bitrefill --help` after connect). Core flow:
+
+```
+search-products  →  get-product-details  →  buy-products  →  get-invoice-by-id
+```
+
+### 1. Search
+
+```bash
+bitrefill search-products --query "Netflix" --country US
+bitrefill --json search-products --query "Netflix" --country US --per_page 5 | jq '.products'
+bitrefill search-products --query "eSIM" --product_type esim --country IT
+bitrefill search-products --query "*" --category games --country US
+```
+
+`--country` = uppercase Alpha-2. `--product_type` = `giftcard` or `esim` (singular). Discover categories: `--query "*"` returns a `categories` array with slugs.
+
+### 2. Details
+
+```bash
+bitrefill get-product-details --product_id "steam-usa" --currency USDC
+```
+
+Returns `packages` array. Each entry has `package_value` — that's the `package_id` for `buy-products`. Ignore the `<&>` compound key.
+
+Three denomination types:
+
+- **Numeric**: `5`, `50`, `200` (pass as number).
+- **Duration**: `"1 Month"`, `"12 Months"` (exact, case-sensitive).
+- **Named**: `"1GB, 7 Days"`, `"PUBG New State 300 NC"` (exact, case-sensitive).
+
+Only values from `get-product-details` accepted. Arbitrary amounts rejected.
+
+### 3. Buy
+
+`--cart_items` = JSON **array**, even single item. Max 15 items. **`--email`** = receipt address (required for guest; optional when signed in).
+
+```bash
+# Guest — crypto + payment link (no login)
+bitrefill buy-products \
+  --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \
+  --payment_method lightning \
+  --return_payment_link true \
+  --email "agent@example.com"
+
+# Signed-in — instant from store credit
+bitrefill buy-products \
+  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
+  --payment_method balance \
+  --email "you@example.com"
+
+# Signed-in — crypto via x402
+bitrefill buy-products \
+  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
+  --payment_method usdc_base
+
+# Duration package
+bitrefill buy-products \
+  --cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]' \
+  --payment_method balance
+
+# Named eSIM
+bitrefill buy-products \
+  --cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]' \
+  --payment_method usdc_base
+```
+
+Response: `invoice_id`, `payment_link`, `x402_payment_url`, `payment_info` (`address`, `paymentUri`, `altcoinPrice`).
+
+### 4. Track / Redeem
+
+```bash
+bitrefill get-invoice-by-id --invoice_id "UUID"   # works guest (save invoice_id from buy response)
+bitrefill list-orders --include_redemption_info true   # signed-in only
+bitrefill get-order-by-id --order_id "ID"              # signed-in only
+```
+
+Invoices expire after 180 minutes. Expired = create new one.
+
+## Critical gotchas
+
+- `--cart_items` must be **array** `[...]`, not object `{...}`. Shell quoting matters: single quotes outside, double inside.
+- Use `package_value` after `<&>`, not the compound key. WRONG `"steam-usa<&>5"`. RIGHT `5`.
+- Named/duration `package_id` exact and case-sensitive. WRONG `"1GB"`. RIGHT `"1GB, 7 Days"`.
+- Country code uppercase Alpha-2. WRONG `us`, `USA`, `"United States"`. RIGHT `US`.
+- `login` / `verify` only when not signed in. After verify, `logout` before switching accounts.
+- Guest: `--payment_method balance` / `cashback` fail — use crypto or sign in first.
+- Signed-in + 2FA: `verify` needs **both** `--code` (email) and `--otp` (authenticator).
+
+## Recommended payment methods (for agents)
+
+**Guest (try first):** `lightning` or `usdc_base` + `x402_payment_url` → `--return_payment_link true` for human/browser pay.
+
+**Signed-in (production):** `balance` (instant, human caps spend via store credit) → `cashback` (rewards balance) → `usdc_base` x402 → `lightning`. Full list: `bitrefill buy-products --help`.
+
+## Source of truth
+
+- <https://github.com/bitrefill/cli> — full command reference, options, flags
+- <https://docs.bitrefill.com/docs/crypto-payments> — payment methods
+- `bitrefill manifest --json` / `bitrefill llm-context` — live tool list + schemas