Marco Pesani

---
name: bitrefill
description: "Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, and eSIMs across 180+ countries, payable in crypto, Lightning, USDC via x402, or pre-funded account balance. Routes the host agent to its highest-fidelity channel (residential browser, MCP server, npm CLI, or REST API) based on detected runtime capabilities, with a dedicated OpenClaw integration guide for chat-channel scenarios. Triggers when the user mentions Bitrefill, gift cards, mobile top-up, eSIM data plan, refilling a phone, or asks to pay or check out with crypto, Lightning, USDC, or x402."
compatibility: "Detects host capabilities at runtime. Paths require: browse — residential-IP browser; MCP — MCP-capable client + Bitrefill OAuth/API key; CLI — Node.js >=18 + shell + npm; API — outbound HTTP + Bitrefill API key (Personal) or API ID/Secret (Business/Affiliate). OpenClaw host gets a dedicated guide."
metadata:
  author: bitrefill
  version: "2.1.0"
  homepage: "https://www.bitrefill.com"
  docs: "https://docs.bitrefill.com"
  repository: "https://github.com/bitrefill/cli"
---

# Bitrefill

Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+ countries and 1,500+ brands. Pay with crypto, Lightning, USDC via x402, or pre-funded account balance. Codes deliver instantly after payment confirms.

This skill **routes by capability, not by use case**. Same intent ("buy a Steam card") plays out differently across hosts. Pick a path below based on what your runtime can do.

## Pick a path

Walk these checks **in order**. First match wins.

1. **Inside OpenClaw?** Check for `~/.openclaw/openclaw.json`, `~/.openclaw/skills/`, or `openclaw` on PATH. If yes → read [host-openclaw.md](references/host-openclaw.md) first. OpenClaw is a superset host: it can run all four paths plus chat-channel scenarios (Telegram purchase, cron top-up, mobile camera). After setup, return here and pick MCP/CLI/API for the actual task.

2. **Browse-only intent (no purchase)?** If the user only wants to explore, compare prices, or learn how products work:
   - Have a residential-IP browser (ChatGPT Atlas, Cursor browser tool, Claude/Playwright Chrome extension, OpenClaw on user host)? → [browse.md](references/browse.md).
   - Datacenter egress only (ChatGPT web/Agent, Gemini consumer, Jules)? `www.bitrefill.com` returns **403 Cloudflare** to datacenter IPs. Use [mcp.md](references/mcp.md) `search-products` / `product-details` instead — they return the same catalog without scraping.

3. **MCP supported?** Bitrefill ships a remote HTTP/SSE MCP at `https://api.bitrefill.com/mcp`. Works on Claude.ai (Pro+), Cowork, Claude Desktop, Claude Code, ChatGPT (Plus+), Atlas, Codex CLI, Gemini CLI, Cursor, OpenCode, OpenClaw. **Highest-fidelity purchase channel — typed tool calls, OAuth or API key, no shell needed.** → [mcp.md](references/mcp.md).

4. **Shell + `npm install` available?** Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, OpenClaw, Jules (ephemeral VM), ChatGPT Agent (sandbox). → [cli.md](references/cli.md).

5. **Outbound HTTP from agent loop?** Anywhere shell exists, plus Claude Code `WebFetch`. Last resort — verbose, no typed validation. → [api.md](references/api.md).

6. **None of the above** (e.g. Gemini consumer free tier): give the user a `bitrefill.com` link and stop.

Don't know which host you're in? Read [capability-matrix.md](references/capability-matrix.md) — per-client cheat sheet maps every leading agent product to its viable paths.

## Top spending safeguards (read full list before any purchase)

This skill enables **real-money transactions**. Codes deliver instantly and digital goods are non-refundable per EU consumer rights.

- **Confirm before buying.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user opts in for the current session.
- **Treat codes as cash.** Never paste in group chats or public channels. Prefer in-memory storage over plain-text logs. Advise user to redeem ASAP.
- **Use a dedicated, low-balance account.** Never give the agent access to high-balance accounts or crypto wallet seeds. This skill is **not a wallet**.
- **Log every purchase.** `invoice_id`, product, amount, payment method.

Full safeguards + per-host hardening (OpenClaw exec-approvals, Cursor auto-approve, Codex sandbox, Claude Code allowlist) → [safeguards.md](references/safeguards.md).

## References

| File | Use when |
|------|----------|
| [browse.md](references/browse.md) | Agent has residential-IP browser; user wants to explore |
| [mcp.md](references/mcp.md) | MCP-capable host; preferred purchase path |
| [cli.md](references/cli.md) | Shell + npm available; headless scripting |
| [api.md](references/api.md) | HTTP-only runtime; Personal / Business / Affiliate REST tiers |
| [host-openclaw.md](references/host-openclaw.md) | Running inside OpenClaw Gateway |
| [capability-matrix.md](references/capability-matrix.md) | Per-client viable paths cheat sheet |
| [safeguards.md](references/safeguards.md) | Spending policy + per-host hardening |
| [troubleshooting.md](references/troubleshooting.md) | Common errors across all paths |

## Source of truth

Skill summarizes and routes. For exhaustive enums (countries, payment methods, full endpoint list), follow link-outs to <https://docs.bitrefill.com>.

FILE:references/api.md
# Path: REST API

Use when: outbound HTTP available but no MCP and no shell. Last resort — verbose, no typed validation. Examples below use `curl` but any HTTP client works.

Base URL: `https://api.bitrefill.com/v2`

## Three tiers

| Tier | Auth | Use case |
|------|------|----------|
| Personal | Bearer token | Personal projects, agent automation |
| Business | Basic auth (`API_ID:API_SECRET`) | Platforms, resellers, BRGC batches, deposits, test products |
| Affiliate | Basic auth | Same as Business + commission tracking, results filtered by `referrer_id` |

## Personal API (agent default)

Get key: <https://www.bitrefill.com/account/developers>.

```bash
export BITREFILL_API_KEY=YOUR_API_KEY
H="Authorization: Bearer $BITREFILL_API_KEY"

# 1. Ping
curl -H "$H" https://api.bitrefill.com/v2/ping
# → {"data":{"message":"pong"}}

# 2. Balance
curl -H "$H" https://api.bitrefill.com/v2/accounts/balance

# 3. Search
curl -H "$H" "https://api.bitrefill.com/v2/products/search?q=amazon"

# 4. Product details
curl -H "$H" https://api.bitrefill.com/v2/products/amazon-us

# 5. Buy (balance, instant)
curl -X POST -H "$H" -H "Content-Type: application/json" \
  -d '{
    "products": [{"product_id":"amazon-us","package_id":"amazon-us<&>50","quantity":1}],
    "payment_method": "balance",
    "auto_pay": true
  }' \
  https://api.bitrefill.com/v2/invoices

# 6. Order / redemption
curl -H "$H" https://api.bitrefill.com/v2/orders/{order_id}
# → data.redemption_info.code, .link, .pin, .instructions
```

For crypto: omit `auto_pay`, set `payment_method: "bitcoin"|"lightning"|"usdc_base"|...`, include `refund_address` for crypto methods, then poll `GET /invoices/{id}` until `status: "complete"`.

## Business API

Apply: <https://www.bitrefill.com/integrate>.

```bash
TOKEN=$(printf "%s:%s" "$BITREFILL_API_ID" "$BITREFILL_API_SECRET" | base64)
H="Authorization: Basic $TOKEN"

curl -H "$H" https://api.bitrefill.com/v2/ping
```

Adds: BRGC (Bitrefill Reusable Gift Card) batches, account deposits via crypto, full product catalog including test products. Same endpoints + `POST /brgc-batches`, `POST /accounts/deposit`.

## Affiliate API

Apply: <https://www.bitrefill.com/affiliate>. Same auth as Business. Adds `GET /commissions` with `after`/`before` date filters. Order/invoice queries return data filtered by `referrer_id` instead of `user_id`.

## Key endpoints

- `GET /ping` — health check (1 req / 3 s)
- `GET /accounts/balance` — current balance
- `GET /products` — paginated catalog (cache locally, refresh daily; 1000 product req/hr quota shared with search)
- `GET /products/search?q=...` — keyword search
- `GET /products/{id}` — product details with `packages` array
- `POST /invoices` — create invoice (max 20 products)
- `POST /invoices/{id}/pay` — pay unpaid balance invoice
- `GET /invoices/{id}` — status
- `GET /orders/{id}` — redemption info
- `POST /esims` — create eSIM invoice (or top-up existing via `esim_id`)
- `GET /esims` / `GET /esims/{id}` — list / get user eSIMs

Webhooks: `webhook_url` field on invoice creation → notification when delivered.

## Test products

Business/Affiliate only. No money charged. Examples: `test-gift-card-code`, etc. Full list: <https://docs.bitrefill.com/docs/test-products>.

## Rate limits

Most endpoints 60 req / 10 min. `/products` and `/products/search` 60 req/min + 1000 product req/hr quota. `/ping` 1 req / 3 s. Full table: <https://docs.bitrefill.com/docs/rate-limits>.

## Source of truth

- <https://docs.bitrefill.com/docs/api-overview> — tier comparison + auth
- <https://docs.bitrefill.com/docs/quickstart-2> — 6-step purchase flow
- <https://docs.bitrefill.com/reference> — full endpoint catalog
- <https://docs.bitrefill.com/docs/error-codes> — error codes
- <https://docs.bitrefill.com/docs/webhooks> — webhook payload spec

FILE:references/capability-matrix.md
# 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)
- **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** for setup + safeguards. Then MCP → CLI → API → Browse as task requires.
- 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/`. If `command -v claude` works = Claude Code. If `command -v codex` = Codex. Look at conversation context for IDE name. When in doubt: try MCP first (broadest support), fall back to CLI, then API.

FILE:references/mcp.md
# Path: MCP

**Preferred purchase channel.** Typed tool calls, OAuth or API key, no shell, works in 10+ hosts.

## Two MCP servers

### eCommerce MCP — for purchases

URL: `https://api.bitrefill.com/mcp` (OAuth) **or** `https://api.bitrefill.com/mcp/YOUR_API_KEY` (header-less, key-in-path).

7 tools:

- `search-products` — keyword + country + category
- `product-details` — packages (denominations) + pricing
- `buy-products` — create invoice
- `get-invoice-by-id` — poll payment status
- `get-order-by-id` — get redemption info (codes, eSIM QR)
- `list-invoices` — invoice history
- `list-orders` — order history

Auth: OAuth (recommended for interactive use) or API key from <https://www.bitrefill.com/account/developers>.

### Development MCP — for docs only

URL: `https://docs.bitrefill.com/mcp`. Indexes the docs site for code-help. **Not for purchases.** Use only when authoring an integration against the Bitrefill API/CLI.

## Per-client setup

### Cursor — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)

```json
{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp",
      "autoApprove": [
        "search-products", "product-details",
        "list-invoices", "get-invoice-by-id",
        "list-orders", "get-order-by-id"
      ]
    }
  }
}
```

Keep `buy-products` **out** of `autoApprove`. Cursor caps at 40 active tools across all servers.

### Claude Code

With the **bitrefill** plugin installed from this repo’s marketplace, the eCommerce MCP is auto-registered; `claude mcp add` below is for manual-only setups.

```bash
claude mcp add bitrefill --url https://api.bitrefill.com/mcp
```

Or edit `~/.claude.json`. Override output cap with `MAX_MCP_OUTPUT_TOKENS` (default 25 000).

### Claude Desktop — `claude_desktop_config.json`

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Windows: `%APPDATA%\Claude\claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "bitrefill": { "url": "https://api.bitrefill.com/mcp" }
  }
}
```

### Claude.ai (web) — Pro / Max / Team / Enterprise

Settings → Connectors → Add custom connector → URL `https://api.bitrefill.com/mcp`. Free tier cannot add custom URLs.

### ChatGPT (Plus / Pro / Business / Enterprise / Edu)

Settings → Apps & Connectors → Add → URL `https://api.bitrefill.com/mcp`. Toggle **Developer Mode** to allow `buy-products` (write tool). Free tier blocked.

### Codex CLI — `~/.codex/config.toml`

```toml
[mcp_servers.bitrefill]
url = "https://api.bitrefill.com/mcp"
bearer_token_env_var = "BITREFILL_API_KEY"
```

OAuth: `codex mcp login bitrefill`.

### Gemini CLI — `~/.gemini/settings.json` (or project `.gemini/settings.json`)

```json
{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp",
      "headers": { "Authorization": "Bearer BITREFILL_API_KEY" }
    }
  }
}
```

OAuth: `gemini mcp auth bitrefill`.

### OpenCode — `opencode.jsonc`

```jsonc
{
  "mcp": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp",
      "headers": { "Authorization": "Bearer BITREFILL_API_KEY" }
    }
  }
}
```

### OpenClaw — see [host-openclaw.md](host-openclaw.md)

```bash
openclaw mcp set bitrefill --url "https://api.bitrefill.com/mcp/$BITREFILL_API_KEY"
```

## Workflow

```
search-products  →  product-details  →  buy-products  →  get-invoice-by-id  →  get-order-by-id
```

1. **Search**: `search-products(query="Steam", country="US", product_type="giftcard")`. `country` is uppercase Alpha-2.
2. **Details**: `product-details(product_id="steam-usa", currency="USDC")`. Returns `packages` array with `package_id` in form `{product_id}<&>{value}`.
3. **Buy**: `buy-products(cart_items=[{product_id, package_id}], payment_method, return_payment_link=true)`. Max 15 items per call.
   - For instant fulfillment: `payment_method: "balance"` + `auto_pay: true`.
   - For agent-driven crypto: `payment_method: "usdc_base"` + `return_payment_link: true` → use `x402_payment_url`.
4. **Poll**: `get-invoice-by-id(invoice_id)`. Statuses: `unpaid` → `payment_detected` → `payment_confirmed` → `complete`.
5. **Redeem**: `get-order-by-id(order_id, include_redemption_info=true)` → returns code / link / eSIM install URL.

Confirm with user before step 3. Logging per [safeguards.md](safeguards.md).

## Caveats

- **ChatGPT** custom MCP requires Plus+; write tools require Developer Mode (admin-enabled on workspaces).
- **Cursor** 40-tool cap across all servers.
- **Claude.ai** consumer needs Pro+ for custom URLs.
- **Code-execution sandboxes** (Claude.ai analysis tool, ChatGPT Code Interpreter) have **no network egress** — they can't call MCP servers; install MCP at the chat level instead.

## Source of truth

- <https://docs.bitrefill.com/docs/ecommerce-mcp>
- <https://docs.bitrefill.com/docs/development-mcp>
- <https://docs.bitrefill.com/docs/setup-guides>
- Per-client setup: <https://docs.bitrefill.com/docs/use-with-cursor>, `/use-with-claude-chat`, `/use-with-claude-code`, `/use-with-chatgpt`

FILE:references/cli.md
# Path: CLI

Use when: shell + `npm install` available, **host has no MCP client** (the 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).

Sandboxed shells must allowlist `registry.npmjs.org` and `api.bitrefill.com`.

## Install

```bash
npm install -g @bitrefill/cli
```

**First-time setup** (validates API key against MCP, stores credentials, auto-configures OpenClaw if `~/.openclaw/openclaw.json` exists):

```bash
bitrefill init                                          # interactive
bitrefill init --api-key $KEY --non-interactive         # CI / agents
bitrefill init --openclaw                               # force OpenClaw integration
```

From source: `git clone https://github.com/bitrefill/cli.git && cd cli && pnpm install && pnpm build && npm link`.

## Auth

Resolution order (first match wins):

1. **`--api-key <key>`** — global flag; can appear before any subcommand.
2. **`BITREFILL_API_KEY`** — environment variable.
3. **`~/.config/bitrefill-cli/credentials.json`** — written by `bitrefill init` (mode `0600`). Overwrite or remove to change the key.
4. **OAuth** — only when no key is available **and** the session is interactive (TTY, not `CI=true`). Browser flow; state under `~/.config/bitrefill-cli/<host>.json` (e.g. `api.bitrefill.com.json`). Clear with `bitrefill logout` (OAuth only; no-op when using API key only).

Generate keys at <https://www.bitrefill.com/account/developers>.

## Global flags

Place **before** the subcommand:

- **`--api-key <key>`** — override env and stored file.
- **`--json`** — stdout is a single JSON value per run (TOON responses decoded to JSON); status and errors go to **stderr**. Use with `jq`.
- **`--no-interactive`** — skip browser OAuth and prompts; also implied when `CI=true` or stdin is not a TTY. Fails fast if no API key.

```bash
bitrefill --json search-products --query "Amazon" --per_page 1 | jq '.products[0].name'
```

## `llm-context`

Regenerates Markdown from the live MCP `tools/list` (params, JSON Schema, example `bitrefill …` and `tools/call` payloads). Use for **CLAUDE.md**, Cursor rules, or **`.github/copilot-instructions.md`**. Connection line shows `…/mcp/<API_KEY>` (redacted), safe to commit.

```bash
bitrefill llm-context -o BITREFILL-MCP.md
# or: bitrefill llm-context > BITREFILL-MCP.md
```

## OpenClaw quick-bootstrap

If OpenClaw is detected (`~/.openclaw/openclaw.json` readable) or you pass `--openclaw`, `bitrefill init` can: write `BITREFILL_API_KEY` to `~/.openclaw/.env`, merge the Bitrefill MCP server into `~/.openclaw/openclaw.json` (env-var reference, no plaintext key in JSON), and emit `~/.openclaw/skills/bitrefill/SKILL.md`. Hardening and channel setup → [host-openclaw.md](host-openclaw.md).

## Workflow

Subcommands are discovered from the remote MCP server (`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.

```bash
# Numeric, crypto via x402
bitrefill buy-products \
  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
  --payment_method usdc_base

# Duration, balance (instant)
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"
bitrefill list-orders --include_redemption_info true
bitrefill get-order-by-id --order_id "ID"
```

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`.

## Recommended payment methods (for agents)

`balance` (instant, no on-chain wait, natural cap) → `usdc_base` with x402 (autonomous payment via `x402_payment_url`) → `lightning`. Other crypto requires polling. 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 llm-context` — live tool list + schemas from the MCP server

FILE:references/troubleshooting.md
# Troubleshooting

Common errors across all paths. Full enum: <https://docs.bitrefill.com/docs/error-codes> and <https://docs.bitrefill.com/docs/References>.

## Browse path

### `403 Forbidden` when fetching bitrefill.com

Cloudflare blocks datacenter IPs. Fix: switch to residential browser (ChatGPT Atlas, Cursor browser, Claude+Chrome ext, OpenClaw on user host) or pivot to MCP/CLI/API.

### Product appears in listing but not purchasable

Geolock at IP level. URL country only filters listed inventory; checkout enforces user's IP. Tell user to access from the matching country (or VPN) — but warn this may violate ToS.

## MCP path

### Tool not visible to agent

- Cursor: 40-tool cap exceeded across all servers. Disable an unused MCP server.
- ChatGPT: Developer Mode off → write tools (`buy-products`) hidden. Toggle in Settings.
- Claude.ai consumer: Free tier cannot add custom MCP URLs. Upgrade to Pro+.
- OpenClaw: `tools.deny: ["bundle-mcp"]` accidentally hiding the server, or per-agent `tools.allow` whitelist excluding it.

### `StreamableHTTPError` with HTML body

Wrong `MCP_URL` — pointing at non-Bitrefill endpoint. Unset `MCP_URL` env var or set to `https://api.bitrefill.com/mcp`.

### OAuth loop in Cursor / Claude.ai

Clear browser cookies for `bitrefill.com`, try a different browser, ensure pop-ups not blocked.

### MCP server filtered out (OpenClaw)

OpenClaw startup safety filter rejects env keys: `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4`. Use only standard `*_API_KEY` / `GITHUB_TOKEN` / proxy vars in MCP server `env` blocks.

### MCP output truncated

Default cap varies by host. Claude Code: `MAX_MCP_OUTPUT_TOKENS=50000` to raise. OpenClaw: `tools.toolResultMaxChars` (default 16000). Use pagination: `--per_page 25`, multiple `list-orders` calls.

## CLI path

### `cart_items` JSON shape error

```
# WRONG (object)
--cart_items '{"product_id": "steam-usa", "package_id": 5}'

# RIGHT (array)
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
```

### `Invalid denomination 'undefined'`

Both `product_id` AND `package_id` required per item.

### `Too big: expected array to have <=15 items`

Split into multiple `buy-products` calls.

### `per_page must be less than 500`

Server limit. Use 500 max.

### `error: required option '--<name>' not specified`

Client-side validation. Add the missing option.

### "Must be one of" enum errors

| Option | Valid values | Common mistakes |
|--------|--------------|-----------------|
| `--payment_method` | `bitcoin`, `lightning`, `ethereum`, `usdc_polygon`, `usdt_polygon`, `usdc_erc20`, `usdt_erc20`, `usdc_arbitrum`, `usdc_solana`, `usdc_base`, `eth_base`, `balance` | `paypal`, `visa`, `USDC_BASE` (case-sensitive) |
| `--product_type` | `giftcard`, `esim` | `giftcards`, `gift_card`, `sim` |
| `--country` | `US`, `IT`, `BR` (uppercase Alpha-2) | `us`, `USA`, `"United States"` |

### Wrong `package_id` for named denominations

Exact, case-sensitive. WRONG `"1GB"`, `"300 nc"`. RIGHT `"1GB, 7 Days"`, `"PUBG New State 300 NC"`. Get exact strings from `get-product-details` `packages` array.

### Compound key in `package_id`

```
# WRONG
--cart_items '[{"product_id": "steam-usa", "package_id": "steam-usa<&>5"}]'

# RIGHT (value after <&>)
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
```

### OAuth hang or auth failure

First-time fix: run `bitrefill init` (validates key, stores `~/.config/bitrefill-cli/credentials.json`).

```bash
export BITREFILL_API_KEY=YOUR_API_KEY   # switch to headless
# or
bitrefill logout                          # clear stale OAuth state only
```

Credentials: API key in `~/.config/bitrefill-cli/credentials.json` (remove file or re-run `bitrefill init` to replace). OAuth tokens/state in `~/.config/bitrefill-cli/<host>.json` (e.g. `api.bitrefill.com.json`); cleared by `bitrefill logout`.

### Empty search results, no error

`found: 0` with no error message. Causes:

- `--category` slug doesn't exist (silent miss).
- Product not available in `--country`.
- `--in_stock true` (default) filters out-of-stock.

Fix: drop `--category`, change `--country`, or `--in_stock false`.

### Unpaid invoices missing from list

`list-invoices` defaults `--only_paid true`. Use `--only_paid false`.

## API path

### `401 Unauthorized`

- Personal: `Authorization: Bearer $BITREFILL_API_KEY` missing or wrong key.
- Business / Affiliate: `Authorization: Basic $(echo -n "$ID:$SECRET" | base64)` malformed.

### `429 Too Many Requests`

Rate limited. Defaults: 60 req / 10 min on most endpoints, 60 req/min on `/products` + `/products/search` plus 1000 product req/hr quota, 1 req / 3 s on `/ping`. Back off + retry. Cache product catalog locally.

### `RESOURCE_NOT_FOUND` on `GET /invoices/{id}`

Bad invoice ID. Verify via `list-invoices`.

### `Product '{slug}' is not available`

Bad product slug. Verify via `search-products`.

### Invoice expired

Invoices expire after **180 minutes**. Cannot re-pay. Create new one.

## OpenClaw-specific

### Cron purchase failed silently

`exec-approvals.json` set to `ask: on-miss` but no operator online to `/approve`. Either pre-approve `bitrefill buy-products` for trusted SKU/amount, or schedule when operator available.

### Pi agent can't see the Bitrefill MCP

Check:

1. `openclaw mcp list` shows entry.
2. `~/.openclaw/openclaw.json` parses (no trailing commas).
3. Agent profile not denying `bundle-mcp` or whitelisting tools narrowly.
4. `BITREFILL_API_KEY` env var set in Gateway environment, not just current shell.

### Mobile node camera tool unavailable

Node not paired or paired but offline. Check `openclaw nodes list`. Re-pair via Control UI (`openclaw dashboard`).

### Telegram message not reaching agent

`channels.telegram.dmPolicy: "pairing"` and sender not paired. Run `openclaw pairing approve telegram <CODE>` (codes expire 1 hr).

## Source of truth

- Bitrefill error codes: <https://docs.bitrefill.com/docs/error-codes>
- Bitrefill error handling: <https://docs.bitrefill.com/docs/References>
- Rate limits: <https://docs.bitrefill.com/docs/rate-limits>
- OpenClaw troubleshooting: <https://docs.openclaw.ai/help> + per-tool pages

FILE:references/host-openclaw.md
# Host: OpenClaw

[OpenClaw](https://docs.openclaw.ai/) is a self-hosted Gateway that bridges chat apps (Telegram, WhatsApp, Slack, Discord, iMessage, Signal, Matrix, Teams, etc.) to coding agents like **Pi**. It is a **superset host**: full host shell, agentskills.io-compatible skill loader, first-class MCP, mobile-node camera/canvas, cron, and multi-channel routing.

This file explains how to install + harden the Bitrefill skill inside OpenClaw and lists scenarios no other host can do. After setup, use the regular path files for the actual workflow.

## 1. Detect OpenClaw

Check **any** of:

- File: `~/.openclaw/openclaw.json` exists.
- Dir: `~/.openclaw/skills/` exists.
- Binary: `command -v openclaw` succeeds.
- Tools in agent loop: `gateway`, `cron`, `nodes`, `canvas`, `sessions_*` (OpenClaw-only).

If yes → continue here. Otherwise → return to [SKILL.md](../SKILL.md) and pick a path.

## 2. Install this skill

Loader paths (increasing precedence): `skills.load.extraDirs` → bundled → `~/.openclaw/skills/` → `~/.agents/skills/` → `<workspace>/.agents/skills/` → `<workspace>/skills/`.

Manual:

```bash
cp -r path/to/bitrefill ~/.openclaw/skills/bitrefill
openclaw skills list   # verify
openclaw gateway restart   # or /new in chat
```

ClawHub (if/when published):

```bash
openclaw skills install bitrefill
openclaw skills update --all
```

Skill is **agentskills.io-compatible** — no rewriting needed. Source: <https://docs.openclaw.ai/tools/skills.md>.

## 3. Install Bitrefill MCP (preferred path)

CLI:

```bash
openclaw mcp set bitrefill --url "https://api.bitrefill.com/mcp/$BITREFILL_API_KEY"
```

Or hand-edit `~/.openclaw/openclaw.json`:

```json
{
  "mcp": {
    "servers": {
      "bitrefill": {
        "url": "https://api.bitrefill.com/mcp",
        "headers": { "Authorization": "Bearer BITREFILL_API_KEY" }
      }
    }
  }
}
```

Transport: SSE/HTTP (default for URL entries) or `transport: "streamable-http"`. The 7 Bitrefill MCP tools surface as ordinary Pi tool calls. Restrict per-agent via `agents.list[].tools.allow`/`deny` if running multi-agent. Source: <https://docs.openclaw.ai/cli/mcp.md>.

Then: see [mcp.md](mcp.md) for tool workflow.

## 4. Install Bitrefill CLI (fallback)

Pi has first-class `exec` tool running on the Gateway host (sandboxing **off** by default).

```bash
exec: npm install -g @bitrefill/cli
```

If Gateway runs in Docker sandbox: declare `setupCommand: "npm install -g @bitrefill/cli"` and ensure `network` is not `none`. Source: <https://docs.openclaw.ai/gateway/sandboxing.md>.

Then: see [cli.md](cli.md).

## 5. Raw API path

`exec` + `curl`, or built-in `web_fetch` tool. No special config. See [api.md](api.md).

## 6. Browser

Pi has `browser` tool. **It uses the Gateway host's IP** — usually residential when Gateway runs on user's machine, but a VPS will hit Cloudflare 403. For richer DOM control attach a Playwright/Chrome MCP. The Mac menubar app drives user's actual Chrome and is fully residential. See [browse.md](browse.md).

## 7. OpenClaw-only scenarios

These are the differentiators. None of the other hosts can do them.

### Buy a gift card from Telegram (away from desk)

User DMs the bot: "buy a $50 Steam US card for me". Pi routes to Bitrefill MCP, prompts confirmation in chat, pays from `balance`, returns redemption code.

**Risk**: redemption codes are cash-like. Never deliver to group chats or via `MEDIA:` URLs. Lock down channel:

```jsonc
{
  "channels": {
    "telegram": {
      "botToken": "TELEGRAM_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": ["123456789"],
      "groups": { "*": { "requireMention": true } }
    }
  }
}
```

Source: <https://docs.openclaw.ai/channels/telegram>.

### Auto-renew mobile top-up monthly

Use `cron` tool to schedule `buy-products` for a fixed phone-top-up SKU on the 1st of each month, paying from `balance`. Heartbeat (default 30 min) polls `get-invoice-by-id` until `complete` then pings the user.

### Multi-channel handoff

Trigger purchase from Slack, deliver redemption code only to user's private Signal DM. Same Gateway, isolated session per channel/sender.

### Mobile camera context

Paired iOS/Android node exposes `camera.snap` and `canvas.*`. User photographs a recipient's request ("100 EUR Decathlon France"), Pi OCRs/parses, runs `search-products` + `buy-products`. Source: <https://docs.openclaw.ai/nodes/index.md>.

### Heartbeat-driven invoice polling

Default 30-min heartbeat or custom `cron` polls `get-invoice-by-id` until `status: complete`, then pushes redemption code to originating channel.

## 8. OpenClaw-specific safeguards

OpenClaw defaults are permissive: sandboxing off, `security: full`, `ask: off`. **Tighten before letting an agent buy on your behalf.**

- **Restrict who triggers purchases**: `channels.<ch>.allowFrom: ["<your_id>"]` + `dmPolicy: "pairing"`. Same for WhatsApp, Signal, Slack, Discord.
- **Require approval for buys**: `~/.openclaw/exec-approvals.json` with `security: allowlist` + `ask: on-miss`. Allowlist `bitrefill *` for read tools; force `/approve` for `bitrefill buy-products` and the MCP `buy-products` call.
- **Isolate Bitrefill agent**: under `agents.list[]` declare a Bitrefill-scoped persona with `tools.deny: ["gateway"]` so the agent **cannot rewrite Gateway config** to bypass approvals. Source: <https://docs.openclaw.ai/tools/exec-approvals.md>.
- **Pre-fund only `balance`** with low cap. **Never** give the agent crypto wallet seeds. Skill is not a wallet.
- **No voice readback of codes**: disable `audio_as_voice` / TTS for the Bitrefill agent. Pi's media pipeline could otherwise speak a cash-like code aloud over Telegram voice notes.
- **No `MEDIA:<url>` for redemption codes**: enforce text-only delivery for the redemption tool output.

## Source of truth

- OpenClaw docs: <https://docs.openclaw.ai/>
- Skills loader: <https://docs.openclaw.ai/tools/skills.md>
- Creating skills: <https://docs.openclaw.ai/tools/creating-skills.md>
- MCP CLI: <https://docs.openclaw.ai/cli/mcp.md>
- Exec tool: <https://docs.openclaw.ai/tools/exec.md>
- Sandboxing: <https://docs.openclaw.ai/gateway/sandboxing.md>
- Exec approvals: <https://docs.openclaw.ai/tools/exec-approvals.md>
- Nodes: <https://docs.openclaw.ai/nodes/index.md>
- Channels: <https://docs.openclaw.ai/channels/telegram>
- Bitrefill skill paths: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md), [safeguards.md](safeguards.md)

FILE:references/browse.md
# 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>

FILE:references/safeguards.md
# Spending Safeguards

This skill enables **real-money transactions**. Purchases are fulfilled instantly after payment confirms. Digital codes are non-refundable per EU consumer rights once delivered.

This page is the **agent-policy layer** — not in upstream Bitrefill or host docs. Read fully before any purchase tool call.

## Universal rules

- **Default: always confirm before purchasing.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user explicitly opts in for the current session.
- **Codes are cash-like.** A gift card code or eSIM QR is bearer money. Store securely. Never share publicly.
- **Prefer in-memory storage.** Don't write codes to plain-text logs, transcripts, or unencrypted files. Programmatically read code → use it → discard.
- **If user asks for the code**: return it but advise to (a) store securely, (b) not share, (c) redeem ASAP.
- **Dedicated, low-balance account.** Never give the agent access to high-balance accounts. Pre-fund only what the agent may spend in the current session.
- **Not a wallet.** This skill does not store private keys or manage crypto wallets. Never give the agent seed phrases, hardware-wallet PINs, or signing keys.
- **Log every purchase.** `invoice_id`, product slug, amount, payment method, timestamp.
- **Refunds**: digital goods refundable only if they don't work as expected (defective code). EU 14-day change-of-mind does **not** apply.
- **Browser redemption fallback.** If trying to redeem on a brand site triggers anti-bot, ask the user to complete redemption manually and return the code.

Terms: <https://www.bitrefill.com/terms/>.

## Per-host hardening

### OpenClaw

Defaults are permissive (sandboxing off, `security: full`, `ask: off`). Tighten:

- `channels.<ch>.allowFrom: ["<your_id>"]` + `dmPolicy: "pairing"` on every channel.
- `~/.openclaw/exec-approvals.json`: `security: allowlist` + `ask: on-miss`. Allowlist read tools (`bitrefill search-products`, `bitrefill list-*`, `bitrefill get-*`). Force `/approve` for `bitrefill buy-products` and the MCP `buy-products` call.
- `agents.list[]` Bitrefill persona with `tools.deny: ["gateway"]` so the agent cannot rewrite Gateway config.
- Disable voice readback (`audio_as_voice` / TTS) for the Bitrefill agent. Codes spoken aloud over voice notes leak.
- Force text-only delivery — no `MEDIA:<url>` for redemption code output.

Full detail in [host-openclaw.md](host-openclaw.md) §8.

### Cursor

`.cursor/mcp.json` `autoApprove` may include read tools. **Never** include `buy-products`:

```json
{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp",
      "autoApprove": [
        "search-products", "product-details",
        "list-invoices", "get-invoice-by-id",
        "list-orders", "get-order-by-id"
      ]
    }
  }
}
```

### Codex CLI

Run with sandbox + approval:

```bash
codex --sandbox workspace-write --ask-for-approval on-request
```

Put `BITREFILL_API_KEY` in a profile (`~/.codex/config.toml` `[profiles.bitrefill]`), not in committed config.

### Claude Code

In `~/.claude/settings.json` (or project `.claude/settings.json`):

```json
{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.ssh", ".env", "*.pem", "**/.bitrefill_token"],
      "denyWrite": ["~/.ssh", ".env"]
    },
    "network": {
      "allow": ["api.bitrefill.com", "registry.npmjs.org"]
    }
  }
}
```

### Claude Desktop / Claude.ai web

Per-tool approval prompts on by default. Keep them on. Don't whitelist `buy-products`.

### ChatGPT (web / Desktop / Atlas / Agent)

Developer Mode required for write tools. Keep it **off** unless actively purchasing. Confirm in-chat before every `buy-products`.

### Gemini CLI

Run with `--sandbox` (Seatbelt / Docker / gVisor). Per-shell command confirmation prompts on by default.

### OpenCode

Set permissions per agent:

```jsonc
{
  "agents": {
    "bitrefill": {
      "permissions": {
        "edit": "ask",
        "bash": { "*": "ask", "bitrefill list-*": "allow", "bitrefill get-*": "allow" },
        "webfetch": "ask"
      }
    }
  }
}
```

## Payment method risk

- `balance` — instant, capped by pre-funded amount. **Lowest blast radius.**
- `usdc_base` via x402 — autonomous payment from agent-controlled wallet. Bound the wallet balance.
- `lightning` — fast, low fee. Manual pay or Lightning-capable agent.
- Other on-chain crypto — slow, requires polling. Higher chance of expired invoices (180 min).

Default recommendation: pre-fund `balance` with low cap → use `payment_method: "balance"` + `auto_pay: true`.

## What to NEVER do

- Pass redemption codes through group chats, public channels, screen-shared sessions, or shared documents.
- Speak codes aloud via TTS / voice notes.
- Store codes in version control, even private repos.
- Give the agent seed phrases or hardware-wallet PINs.
- Auto-approve `buy-products` in any host's MCP config.
- Run the Bitrefill skill from an account with stored payment cards or high balances.

## Source of truth

- Bitrefill ToS: <https://www.bitrefill.com/terms/>
- Refund policy: <https://docs.bitrefill.com/docs/refunds>
- Path setup: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md)
- OpenClaw hardening: [host-openclaw.md](host-openclaw.md)

---
name: bitrefill-cli
description: "Buy gift cards, mobile top-ups, and eSIMs on Bitrefill. Pay with crypto and x402. 1,500+ brands, 180+ countries"
compatibility: "Node.js >=18, npm, Bitrefill account. Auth: BITREFILL_API_KEY env var (headless) or OAuth token. Payment: a crypto wallet able to send crypto or pay to x402 endpoint (USDC on Base)."
metadata:
  author: bitrefill
  version: "1.5.0"
  homepage: "https://www.bitrefill.com"
  repository: "https://github.com/bitrefill/cli"
---

# Bitrefill CLI

Search, purchase, and deliver digital goods (gift cards, mobile top-ups, eSIMs) via the [Bitrefill CLI](https://github.com/bitrefill/cli).

## Requirements

- A **Bitrefill account** is required to use this skill. Authentication is done via the Bitrefill API key or OAuth. See [Setup](#setup) for more details.
- A **crypto wallet** is required to send crypto or pay to x402 endpoint (USDC on Base). NOT PROVIDED BY THIS SKILL.
- "Browser usage" MCP or CLI is suggested for the agent to **redeem the code on the brand's website**, for fully autonomous shopping experiences. NOT PROVIDED BY THIS SKILL.

## Supported Payment Methods

Best payment experiences for instant agentic payments is store credits via **`balance`**, then USDC on Base via x402, then Lightning. All the other crypto payments requirse the agent to poll the invoice status to confirm payment.

CLI returns the full list with `bitrefill buy-products --help`

- **`balance`** — Instant fulfillment, no on-chain wait. User pre-funds at [bitrefill.com](https://www.bitrefill.com). Natural spending cap.
- **`usdc_base`** with x402 — Use `--return_payment_link true` (default) to get `x402_payment_url`. An x402-capable agent completes payment autonomously over Base.
- **`lightning`** — Lightning — `lightningInvoice`, `satoshiPrice`
- **`ethereum`** — Ethereum mainnet (ETH) — `address`, `paymentUri`, `altcoinPrice`
- **`eth_base`** — Base (8453), native ETH
- **`usdc_base`** — Base (8453), USDC
- **`usdc_arbitrum`** — Arbitrum (42161), USDC
- **`usdc_polygon`** — Polygon (137), USDC
- **`usdc_erc20`** — Ethereum (1), USDC
- **`usdc_solana`** — Solana, USDC
- **`usdt_polygon`** — Polygon (137), USDT
- **`usdt_erc20`** — Ethereum (1), USDT
- **Payment cards, local payment methods and other crypto payment methods are available in the checkout page returned by the `--return_payment_link true` option.**

## Spending Safeguards

This skill enables **real-money transactions**. Purchases are fulfilled instantly after payment is confirmed.

- **Default: always confirm before purchasing.** Present product, denomination, price, and payment method; wait for explicit approval before `buy-products`. Autonomous purchasing only when the user explicitly opts in for the current session.
- As soon as digital goods are delivered, they are refundable only in case they don't work as expected. According to the **EU Consumer Rights**, digital goods like gift card codes are not subject to 14-day change of mind policy.
- A **gift card code can be considered cash-like**, so it should be stored securely and not shared publicly. Only the agent's owner should have access to the code. Prefer encrypted data storage for the code rather than plain text.
- Try as much as possible to avoid re-writing the digital codes. If possible, prefer **in-memory storage** until the code is redeemed, and to programmatically access and use it only then.
- If the user asks for the code, return it but advise them to **store it securely, not share it publicly, and use it as soon as possible**.
- Use a **dedicated, limited-balance account** — never give agents access to high-balance accounts.
- **Terms of Service:** https://www.bitrefill.com/terms/ contains important information about the refund policy and purchase limits.
- **Log every purchase:** `invoice_id`, product, amount, payment method.
- **Not a wallet:** This skill is not a wallet. It is a tool for buying products on Bitrefill. It is not responsible for storing private keys or managing your crypto wallet.
- **Browser usage:** When trying to redeem a code on the brand's website, anti-bot protection mechanisms may block the agent. In that case, ask the user if they want to complete manually the redemption process and, in case, return the code to the user.

## Setup

### 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`

### Auth

Generate an API key at [bitrefill.com/account/developers](https://www.bitrefill.com/account/developers):

```bash
export BITREFILL_API_KEY=YOUR_API_KEY
```

Alternative: run any command without an API key to trigger browser-based OAuth. Token stored at `~/.config/bitrefill-cli/api.bitrefill.com.json`. Clear with `bitrefill logout`.

### Environment

| Variable | Purpose |
|----------|---------|
| `BITREFILL_API_KEY` | Headless auth (skips OAuth) |

## Core Workflow

```
search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
```

### 1. Search

```bash
bitrefill search-products --query "Netflix" --country US
bitrefill search-products --query "eSIM" --product_type esim --country IT
bitrefill search-products --query "*" --category games
```

`--country` must be **uppercase Alpha-2 ISO** (`US`, `IT`, `BR`). `--product_type`: `giftcard` or `esim` (singular).

**Discovering categories:** Search with `--query "*"` — the response includes a `categories` array with slugs and counts (e.g. `food`, `games`, `streaming`). Add `--country` to see categories available in a specific country. Use these slugs as `--category` values.

### 2. Get Details

```bash
bitrefill get-product-details --product_id "steam-usa"
```

Returns a `packages` array. Each entry has a `package_value` — use this as `package_id` in `buy-products`.

**Ignore compound keys** like `steam-usa<&>5` — use only the value after `<&>`.

Three denomination types:

- **Numeric:** `5`, `50`, `200` (pass as number)
- **Duration:** `"1 Month"`, `"12 Months"` (exact string, case-sensitive)
- **Named:** `"1GB, 7 Days"`, `"PUBG New State 300 NC"` (exact string, case-sensitive)

Only values from `get-product-details` are accepted — arbitrary amounts are rejected.

### 3. Buy

`--cart_items` must be a **JSON array** `[...]`, even for a single item.

```bash
# Numeric
bitrefill buy-products \
  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
  --payment_method usdc_base

# Duration
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 includes `invoice_id`, `payment_link`, and `x402_payment_url`.

Max 15 items per call.

### 4. Track

```bash
bitrefill get-invoice-by-id --invoice_id "UUID"
bitrefill list-orders --include_redemption_info true
```

## Critical Gotchas

**`cart_items` must be array, not object:**

```bash
# WRONG
--cart_items '{"product_id": "steam-usa", "package_id": 5}'
# RIGHT
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
```

**Use `package_value` after `<&>`, not the compound key:**

```bash
# WRONG: "steam-usa<&>5"  →  RIGHT: 5
```

**Named/duration `package_id` must be exact, case-sensitive:**

```bash
# WRONG: "1GB"    →  RIGHT: "1GB, 7 Days"
# WRONG: "300 nc" →  RIGHT: "PUBG New State 300 NC"
```

**Country codes must be uppercase Alpha-2:**

```bash
# WRONG: us, USA, "United States"  →  RIGHT: US
```

## References

Load when needed:

| Reference | Use when |
|-----------|----------|
| [commands](references/commands.md) | Full option tables for any command |
| [payment](references/payment.md) | Payment methods list, x402 protocol, response fields |
| [troubleshooting](references/troubleshooting.md) | Errors beyond the critical gotchas above |

FILE:references/troubleshooting.md
# Troubleshooting

Covers errors beyond the [critical gotchas](../SKILL.md#critical-gotchas) in the main skill file.

## "Must be one of" errors

The CLI validates enums client-side.

| Option | Valid values | Common mistakes |
|--------|-------------|-----------------|
| `--payment_method` | `bitcoin`, `ethereum`, `lightning`, `usdc_polygon`, `usdt_polygon`, `usdc_erc20`, `usdt_erc20`, `usdc_arbitrum`, `usdc_solana`, `usdc_base`, `eth_base`, `balance` | `paypal`, `visa`, `USDC_BASE` (case-sensitive) |
| `--product_type` | `giftcard`, `esim` | `giftcards` (plural), `gift_card`, `sim` |

## Missing required options

Omitting `--cart_items` or `--product_id` when required: `error: required option '--<name> <value>' not specified`. The CLI enforces this before connecting to the server.

## Cart exceeds 15 items

Server rejects: `Too big: expected array to have <=15 items`. Split into multiple `buy-products` calls.

## `per_page` exceeds 500

Server rejects: `per_page must be less than 500`.

## Malformed JSON in `--cart_items`

`Unexpected token ... is not valid JSON`. Shell quoting matters — single quotes around JSON, double quotes inside:

```bash
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
```

## Missing `package_id` in cart item

`Invalid denomination 'undefined'`. Both `product_id` and `package_id` are required per item.

## Invoice / Product not found

- `get-invoice-by-id` with bad ID: `Invoice not found` (RESOURCE_NOT_FOUND)
- `buy-products` with bad slug: `Product '<slug>' is not available` (RESOURCE_NOT_FOUND)

Verify slugs via `search-products`, invoice IDs via `list-invoices`.

## Wrong `MCP_URL`

Setting `MCP_URL` to a non-Bitrefill endpoint: `StreamableHTTPError` with the remote server's HTML body. Unset the variable or point it to `https://api.bitrefill.com/mcp`.

## OAuth / auth failures

If the CLI hangs or fails on startup:

1. Switch to API key auth: `export BITREFILL_API_KEY=YOUR_API_KEY`
2. Or clear stale credentials: `bitrefill logout`, then re-run your command
3. Credentials file: `~/.config/bitrefill-cli/api.bitrefill.com.json`

## Empty search results

`found: 0` with no error:

- `--category` slug doesn't exist (no error, just empty)
- Product not available in the specified `--country`
- `--in_stock true` (default) filters out-of-stock products

Fix: remove `--category`, change `--country`, or set `--in_stock false`.

## Unpaid invoices

`list-invoices` shows only paid by default. See all: `--only_paid false`.

Invoices expire after 180 minutes. Expired invoices cannot be re-paid — create a new one.

FILE:references/payment.md
# Payment Reference

## Recommended for Agents

- **`balance`** — Instant fulfillment, no on-chain wait. User pre-funds at [bitrefill.com](https://www.bitrefill.com). Natural spending cap.
- **`usdc_base`** with x402 — Use `--return_payment_link true` (default) to get `x402_payment_url`. An x402-capable agent completes payment autonomously over Base.

Suggest `balance` or `usdc_base` first. Fall back to other methods only if the user explicitly requests them.

## Payment Methods

| Method | Chain / Asset |
|--------|---------------|
| `bitcoin` | Bitcoin (SegWit) — `address`, `BIP21`, `lightningInvoice`, `satoshiPrice` |
| `lightning` | Lightning — `lightningInvoice`, `satoshiPrice` |
| `ethereum` | Ethereum mainnet (ETH) — `address`, `paymentUri`, `altcoinPrice` |
| `eth_base` | Base (8453), native ETH |
| `usdc_base` | Base (8453), USDC |
| `usdc_arbitrum` | Arbitrum (42161), USDC |
| `usdc_polygon` | Polygon (137), USDC |
| `usdc_erc20` | Ethereum (1), USDC |
| `usdc_solana` | Solana, USDC SPL |
| `usdt_polygon` | Polygon (137), USDT |
| `usdt_erc20` | Ethereum (1), USDT |
| `balance` | Bitrefill account credit — paid from balance, no address |

## Response Modes

- **`--return_payment_link true`** (default) — returns `payment_link` (browser checkout), `x402_payment_url` (programmatic pay), plus raw `payment_info`.
- **`--return_payment_link false`** — raw payment details only: `address`, `amount`, `paymentUri` (+ `lightningInvoice` for Bitcoin). No `payment_link` or `x402_payment_url`.

## x402 Protocol

[x402](https://docs.x402.org/) enables HTTP 402-based crypto payments:

1. `GET x402_payment_url` → receive 402 + payment instructions (Base64 JSON: amount, `payTo`, networks, timeout)
2. Send crypto to the specified address
3. Resubmit request with payment proof

For agents and automated tools. Humans use `payment_link` instead.

FILE:references/commands.md
# Command Reference

All commands accept `--api-key <key>` (or `BITREFILL_API_KEY` env var) for headless auth. Run `bitrefill --help` for the current list.

## search-products

```bash
bitrefill search-products --query "Netflix" --country US
```

| Option | Description | Default |
|--------|-------------|---------|
| `--query` | Brand name or `*` for all (fulltext, not semantic) | `*` |
| `--country` | Uppercase Alpha-2 ISO (`US`, `IT`, `BR`) | `US` |
| `--product_type` | `giftcard` or `esim` (singular) | — |
| `--category` | Category slug (`games`, `food`, `streaming`) | — |
| `--in_stock` | `true`/`false` | `true` |
| `--page` | 1-indexed page number | `1` |
| `--per_page` | 1–500 | `25` |

## get-product-details

```bash
bitrefill get-product-details --product_id "steam-usa" --currency USDC
```

| Option | Description | Default |
|--------|-------------|---------|
| `--product_id` | Product slug from search results (required) | — |
| `--currency` | `BTC`, `ETH`, `USDT`, `USDC`, `SOL`, `USD`, `EUR`, `GBP`, `AUD`, `CAD`, `INR`, `BRL` | `BTC` |
| `--language` | Language code for descriptions | `en` |

## buy-products

```bash
bitrefill buy-products \
  --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
  --payment_method usdc_base
```

| Option | Description | Default |
|--------|-------------|---------|
| `--cart_items` | JSON array of `{product_id, package_id}` objects, 1–15 items (required) | — |
| `--payment_method` | See [payment.md](payment.md) (required) | — |
| `--return_payment_link` | `true` → `payment_link` + `x402_payment_url`; `false` → raw `address`/`paymentUri` | `true` |

Response fields (when `return_payment_link true`):

- `invoice_id` — poll status with `get-invoice-by-id`
- `payment_link` — browser checkout URL
- `x402_payment_url` — programmatic x402 payment endpoint
- `payment_info.address` — on-chain destination
- `payment_info.paymentUri` — EIP-681 URI with contract + amount
- `payment_info.altcoinPrice` — amount in payment token

## list-invoices

```bash
bitrefill list-invoices --only_paid false --limit 10
```

| Option | Description | Default |
|--------|-------------|---------|
| `--limit` | 1–50 | `25` |
| `--start` | Pagination offset | `0` |
| `--after` | ISO 8601 date filter | — |
| `--before` | ISO 8601 date filter | — |
| `--only_paid` | `true` hides unpaid invoices | `true` |
| `--include_orders` | Include order details | `true` |

## get-invoice-by-id

```bash
bitrefill get-invoice-by-id --invoice_id "UUID"
```

| Option | Description | Default |
|--------|-------------|---------|
| `--invoice_id` | UUID of the invoice (required) | — |
| `--include_orders` | Include order details | `true` |
| `--include_redemption_info` | Include redemption codes/links | `false` |
| `--include_access_token` | Include unauthenticated access token | `false` |

## list-orders

```bash
bitrefill list-orders --limit 5 --include_redemption_info true
```

| Option | Description | Default |
|--------|-------------|---------|
| `--limit` | 1–50 | `25` |
| `--start` | Pagination offset | `0` |
| `--after` / `--before` | ISO 8601 date filters | — |
| `--include_redemption_info` | Include redemption codes/links | `false` |

## get-order-by-id

```bash
bitrefill get-order-by-id --order_id "69af584e8a2639d14ac35e96"
```

Returns redemption code/link if the order is unsealed (paid and delivered).

| Option | Description | Default |
|--------|-------------|---------|
| `--order_id` | Order ID (required) | — |
| `--include_redemption_info` | Include redemption codes/links | `true` |

## logout

```bash
bitrefill logout
```

Deletes stored OAuth credentials from `~/.config/bitrefill-cli/`.

---
name: bitrefill-website
description: "Browse and explore Bitrefill (bitrefill.com): discover gift cards, mobile top-ups, and eSIMs; search by brand, category, or country; compare products and denominations; understand pricing, availability, and how each product type works. Use when the user mentions Bitrefill, gift cards, phone top-up, or eSIM for travel."
compatibility: "No credentials or API access required. Instruction-only skill for navigating bitrefill.com."
metadata:
  author: bitrefill
  version: "1.2.1"
  homepage: "https://www.bitrefill.com"
---

# Bitrefill Website Skill

Use this skill when the user wants to **explore** Bitrefill (bitrefill.com): learn about products, search, compare, or understand pricing and availability. Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) and offers Bitcoin/Lightning services. All products are delivered digitally.

> **Programmatic access & purchases:** For searching via API, buying products, managing orders, or any automated workflow, use the **bitrefill-cli** skill instead. This skill is browse-only — it helps users navigate and understand the website.

## When to Use This Skill

Activate when the user:
- Mentions **Bitrefill** or bitrefill.com
- Asks how to **search**, **find**, or **compare** products on Bitrefill
- Needs **information** (pricing, availability, country restrictions, denominations)
- Wants to understand what Bitrefill offers or how a product type works

**Redirect to bitrefill-cli** when the user wants to:
- **Buy** a product, make a purchase, or pay with crypto
- Use the Bitrefill **API** or **MCP endpoint** programmatically
- Manage **orders** or **invoices**
- Perform any **automated** or **CLI-based** workflow

If the request is vague (e.g. "I need a gift"), ask what type of product and for whom (country/interests).

## Quick Decision: What Does the User Want to Do?

```
User intent?
├─ Learn what Bitrefill offers / product types     → See "Product types at a glance" below; details in references/product-types.md
├─ Search or browse for a product                 → references/search-and-browse.md
└─ Get detailed info (price, country, how it works)→ references/search-and-browse.md
```

## Product Types at a Glance

| Product type | What it is | Main URL | Load details when needed |
|--------------|------------|----------|---------------------------|
| **Gift cards** | Digital gift cards (shopping, streaming, gaming, food, travel) | bitrefill.com/{country}/{lang}/gift-cards/ | references/product-types.md, references/supported-categories.md |
| **Mobile top-ups** | Prepaid airtime/data for a phone number (200+ countries) | bitrefill.com/refill/ | references/product-types.md |
| **eSIMs** | Travel data plans (data-only, QR activation, 190+ countries) | bitrefill.com/esim/all-destinations or bitrefill.com/{country}/{lang}/esims/ | references/product-types.md |
| **Bitcoin / Lightning** | Channel opening, liquidity, payment tools | bitrefill.com (relevant sections) | references/product-types.md (brief) |
| **Account & Auth** | Signup, login, password reset, referral program | bitrefill.com/signup, /login | references/account-and-auth.md |

**Critical:** Many products are **country- or region-specific**. Always confirm or infer the user's country (and, for top-ups, carrier) before recommending a product or flow.

- **Country in URL:** The first path segment is **country**, the second is **language** (e.g. `/us/en/gift-cards/`, `/mx/es/gift-cards/`). The country segment filters the **inventory shown** to gift cards usable in that country. To see a specific country's inventory, use that country in the URL.
- **Geolock:** Purchasability is enforced at **IP level**, not by the URL. If a product is not purchasable, it is due to the user's IP/location, not the country chosen in the URL.

## Task Flows (High Level)

### Browse or search

1. Identify **product type** (gift card / top-up / eSIM) and **country** (and carrier for top-ups if known).
2. For **quick discovery** of gift cards, send the user directly to search results: `https://www.bitrefill.com/{country}/{lang}/gift-cards/?q={query}` (e.g. `https://www.bitrefill.com/us/en/gift-cards/?q=amazon`) — no need to navigate from the home page.
3. For **eSIM discovery by destination**, send the user to **bitrefill.com/esim/all-destinations** to browse 190+ countries/regions.
4. Otherwise direct to the right section or use site search; help filter by category, brand, or amount.
5. For depth (categories, brands, denominations): **references/search-and-browse.md**, **references/supported-categories.md**.
6. **Category = path.** To list a category (or subcategory), use `/{country}/{lang}/gift-cards/{category-slug}/`.
7. **Subcategories:** Some categories have subcategories (e.g. travel → flights, train, bus). Same path pattern; slug = subcategory.
8. **Listings filters & sort:** Gift-card listings (all / category / subcategory) support query params: **filters** — `redemptionMethod` (online|instore), `minRating` (2–5), `minRewards` (1–10 cashback); **sort** — `s=2` (A–Z), `s=3` (recently added), `s=4` (cashback); default = popularity. See references/search-and-browse.md.

## Tips and Common Pitfalls

- **Country first:** Use the country in the URL to show the right inventory (cards usable in that country). Region-locked products (e.g. Amazon US vs UK) are the main source of errors — align product country with the user's.
- **Geolock vs URL:** Whether a product can be bought is determined by the user's IP (geolock), not by the country in the URL. The URL only controls which inventory is listed.
- **Refunds:** Digital goods are typically non-refundable once delivered; set expectations before purchase.

## Limitations

- **No scraping:** Cloudflare blocks automated access to www.bitrefill.com. Do not use firecrawl or direct scraping — requests return 403.
- **No API access:** This skill does not use the Bitrefill API or MCP endpoint. For programmatic access (search, buy, order management), use the **bitrefill-cli** skill.

## References

Load only when the agent needs more detail:

| Reference | Use when |
|-----------|----------|
| [product-types](references/product-types.md) | Explaining gift cards vs top-ups vs eSIMs, or how each works on the site |
| [search-and-browse](references/search-and-browse.md) | User wants to find or filter products |
| [supported-categories](references/supported-categories.md) | Listing categories or popular brands (gift cards, etc.) |

FILE:references/search-and-browse.md
# Search and Browse on Bitrefill

Use this reference when the user wants to **find** a product: search by brand, browse by category, or filter by country/amount.

## Entry Points by Product Type

| Product type      | Main URL                              | How to narrow down |
|-------------------|---------------------------------------|---------------------|
| Gift cards        | bitrefill.com/{country}/{lang}/gift-cards/ | Category, country, brand search |
| Mobile top-ups    | bitrefill.com/refill/                 | Country → carrier → amount |
| eSIMs             | bitrefill.com/{country}/{lang}/esims/ | Country/region → data/duration |
| eSIM all-destinations | bitrefill.com/esim/all-destinations | Browse 190+ countries/regions; then open locale-specific product page |
| All categories    | bitrefill.com/categories              | Overview of everything |

## Country in URL vs Geolock

- **Country in URL:** URL path is **country** then **language** (e.g. `/us/en/gift-cards/`, `/mx/es/gift-cards/`). The country segment **filters which gift cards are listed** — only those usable in that country. To see a specific country's inventory, use that country as the first path segment.
- **Geolock:** Enforced at **IP level**. Whether a product is purchasable depends on the user's IP/location, not on the country in the URL. A product may appear in the listing but be unavailable at checkout if the user's IP is outside the allowed region.

## How to Search

- **Quick discovery (direct URL):** Use `https://www.bitrefill.com/{country}/{lang}/gift-cards/?q={query}` — e.g. `https://www.bitrefill.com/us/en/gift-cards/?q=amazon`. The page **prioritizes in-country products** but **shows results from all countries**. Search covers **gift cards, phone top-ups, and eSIMs**.
- **Site search:** Use the search on bitrefill.com (brand names, product names) to jump to relevant product pages.
- **Gift cards:** Search by brand or browse categories. Use the **country in the URL** to focus on cards usable in that country (in-country results are prioritized).
- **Top-ups:** No generic "search"; at bitrefill.com/refill/, user selects **country** first, then **carrier** (or enter number for carrier detection), then **amount**.
- **eSIMs:** Filter by **destination country or region**, then by **data size** and **validity** (e.g. 7 days, 30 days).

## eSIM discovery

- For "which countries/regions exist" or "browse all eSIMs": send the user to **https://www.bitrefill.com/esim/all-destinations**.
- From that hub, "View plans" links go to `/{country}/{lang}/esims/bitrefill-esim-{slug}/` (locale may differ by user; slug is country/region name in kebab-case, e.g. `bitrefill-esim-japan`, `bitrefill-esim-global`, `bitrefill-esim-taiwan`).

## Listing Filters and Sort (Gift Cards)

Applicable to **all gift-card listings** (all gift cards, category, or subcategory), e.g. `/{country}/{lang}/gift-cards/` or `/{country}/{lang}/gift-cards/food/`.

| Param | Values | Description |
|-------|--------|-------------|
| `redemptionMethod` | `online`, `instore` | Redemption method filter |
| `minRating` | `2`, `3`, `4`, `5` | Minimum review vote (stars) |
| `minRewards` | `1`–`10` | Minimum cashback (rewards) |
| `s` | `2` = A–Z, `3` = recently added, `4` = cashback | Sort; default = popularity |

**Example:** `https://www.bitrefill.com/us/en/gift-cards/food/?minRating=5&minRewards=4&redemptionMethod=instore`  
**Sort example:** `https://www.bitrefill.com/us/en/gift-cards/?s=2` (A–Z).

## Filters That Matter

1. **Country / region**  
   Set via **URL** (first path segment = country, e.g. `/us/en/`) to show inventory for that country. Most gift cards and all top-ups/eSIMs are country- or region-specific. Establish the user's country (and for top-ups, carrier) before recommending a product.

2. **Category (gift cards)**  
   Shopping, Entertainment, Gaming, Food & Delivery, Travel, etc. Helps when the user says "streaming" or "gaming" rather than a brand. See references/supported-categories.md for full list.

3. **Brand**  
   When the user names a brand (e.g. Amazon, Steam), search or go directly to that brand’s page and then check country/denomination.

4. **Denomination / amount**  
   Shown on the product page. For gift cards, fixed or custom; for top-ups, carrier-specific; for eSIMs, data + duration.

## Suggested Flow for the Agent

1. **Clarify:** Product type (gift card / top-up / eSIM) and country (and carrier for top-ups if possible).
2. **Direct:** Send user to the right URL (gift-cards, refill, esims) or use search.
3. **Remind:** Check country and (for gift cards) denomination so the card is usable for the recipient.

## URL Patterns

Bitrefill uses different URL patterns depending on the page:

- **Category listing (gift cards):** `/{country}/{lang}/gift-cards/{category-slug}/` — use the path for a category or subcategory (e.g. `/us/en/gift-cards/flights/`). Do not use `?category=...` for “only this category”; it can return the full catalog filtered. Add listing filters/sort as query params (see "Listing Filters and Sort" above).
- **Locale-prefixed:** `/{country}/{lang}/gift-cards/`, `/{country}/{lang}/esims/`. Single eSIM: `/{country}/{lang}/esims/bitrefill-esim-{destination-slug}/`. Product: `/{country}/{lang}/gift-cards/{product-slug}/`.
- **Query-param locale:** `/refill/?hl=it`, `/card/?hl=it` — older pages use `?hl=` parameter
- **No locale:** `/login`, `/signup`, `/refer-a-friend`, `/blog/`, `/esim/all-destinations` (eSIM hub)

For “which X are supported” or “how does this work,” use **help.bitrefill.com** or the product page; category pages often don’t expose full product/coverage lists in static HTML.

## Internal Search Endpoint

The site uses `/api/omni` as its internal product search endpoint (browser-only, requires cookies). For programmatic product search, use the **bitrefill-cli** skill instead.

For a full list of categories and popular brands, use references/supported-categories.md.

FILE:references/supported-categories.md
# Supported Product Categories

Categories sourced from the Bitrefill `/api/omni` response. For the latest offerings and availability, always check [bitrefill.com](https://www.bitrefill.com).

## Gift Cards

Digital gift cards for popular brands, delivered as redeemable codes.

### Categories (from API)

| Category slug | Description |
|---------------|-------------|
| automobiles | Automotive brands |
| top-products | Most popular products |
| all-gift-cards | All available gift cards |
| retail | General retail stores |
| apparel | Clothing and fashion |
| health-beauty | Health and beauty products |
| home | Home and household |
| electronics | Electronics and tech |
| pets | Pet supplies and services |
| food | Food and groceries |
| restaurants | Restaurant gift cards |
| food-delivery | Food delivery services |
| payment-cards | Prepaid payment cards |
| multi-brand | Multi-brand / multi-store cards |
| groceries | Grocery stores |
| streaming | Streaming services (video, music) |
| games | Gaming platforms and credits |
| travel | General travel |
| flights | Flight bookings |
| cruises | Cruise bookings |
| train | Train travel |
| bus | Bus travel |
| car-rental | Car rental services |
| pharmacy | Pharmacy and drugstores |
| music | Music services and stores |
| entertainment | Entertainment and media |
| literature | Books and reading |
| experiences | Experience gifts |
| gifts | General gift options |
| voip | VoIP and calling services |
| utility-bills | Utility bill payments |
| digital-wallet | Digital wallet top-ups |
| online-marketplaces | Online marketplace credits |
| online-travel-agencies | OTA credits (Booking, etc.) |
| accommodation | Hotel and accommodation |
| department-stores | Department store cards |
| sports-n-outdoors | Sports and outdoor brands |
| phone-services | Phone service credits |
| transportation | Transportation services |
| gasoline | Fuel and gas stations |
| vpn | VPN service subscriptions |
| payment-voucher | Payment vouchers |
| kids | Kids and family |
| amazon | Amazon gift cards (all regions) |
| bitcoin | Bitcoin-related products |
| game-stores | Game store credits |
| in-game-currencies | In-game currency top-ups |
| cosmetics | Cosmetics and beauty |
| spa | Spa and wellness |
| natural-herbal-care | Natural and herbal care |
| electricity | Electricity bill payments |

Availability is per country. Many brands have region-specific cards (e.g. Amazon US, UK, DE).

## Mobile Top-ups (Refills)

Prepaid airtime and data for mobile numbers in 200+ countries.

### Subcategories (from API)

| Category slug | Description |
|---------------|-------------|
| refill | Standard airtime top-up |
| data | Data-only packages |
| pin | PIN-based top-ups |
| bundles | Combined voice + data bundles |
| dth | Direct-to-home (TV recharge) |

- Most major carriers supported.
- Top-up is applied to the phone number.
- Denominations vary by carrier and country.

## eSIMs

Travel data plans for 190+ countries.

- **Discovery hub:** Full list and browse by All / Country / Region at **bitrefill.com/esim/all-destinations**.
- Product slugs are kebab-case (e.g. `bitrefill-esim-japan`, `bitrefill-esim-global`, `bitrefill-esim-taiwan`).
- Data-only (no voice/SMS).
- Durations: e.g. 1, 7, 15, 30 days; data from around 1GB to unlimited.
- Regional plans (e.g. Europe, Asia, Americas).
- Activate via QR code; install before or during travel.
- Compatible with most modern smartphones (e.g. iPhone XS+, recent Android).

## Bitcoin & Lightning Services

- Lightning channel opening and liquidity services.
- Bitcoin payment processing tools.

## General Notes

- **Country restrictions:** Many products are region-locked. Verify the user's country matches the product.
- **Denominations:** Gift card values typically from about $5 to $500, depending on brand.
- **Currency:** Prices can be shown in the user's local currency; crypto is converted at checkout.
- **Catalog changes:** Bitrefill adds and updates brands and products; use the site or API for the current catalog.

FILE:references/product-types.md
# Product Types on Bitrefill

Bitrefill offers four main product families. Use this reference when the user needs to understand what each type is, where to find it on the site, or how it works.

## Gift Cards

**What they are:** Digital gift cards for brands (shopping, streaming, gaming, food, travel). Delivered as redeemable codes, usually by email and on the order page.

**On the site:** bitrefill.com/{country}/{lang}/gift-cards/ — filter by category, country, or search by brand.

**Important:**
- **Region-locked:** Most brands have per-country cards (e.g. Amazon US, UK, DE). Always match the user's (or recipient's) country.
- **Denominations:** Fixed tiers (e.g. $25, $50) or custom amounts depending on brand. Shown on each product page.
- **Use:** User redeems the code on the brand's website or app. See references/use-and-activate.md.

**Categories (from API):** automobiles, top-products, retail, apparel, health-beauty, home, electronics, pets, food, restaurants, food-delivery, streaming, games, travel, entertainment, and many more. Full list: references/supported-categories.md.

---

## Mobile Top-ups

**What they are:** Prepaid airtime (and sometimes data bundles) applied directly to a phone number. Available in 200+ countries.

**On the site:** bitrefill.com/refill/ — select country, then carrier, then amount.

**Important:**
- **Carrier and number:** User must provide the phone number and (if needed) select the correct carrier. The site often detects carrier from number.
- **Denominations:** Vary by carrier and country; shown after selecting carrier.
- **Refill subcategories (from API):** refill, data, pin, bundles, dth.
- **Delivery:** Airtime is applied to the number shortly after payment (usually minutes).
- **Use:** No code to redeem; confirm balance on the phone or carrier account. See references/use-and-activate.md.

---

## eSIMs

**What they are:** Data-only travel plans. User installs an eSIM via QR code; no physical SIM. For use when traveling (190+ countries).

**On the site:** Browse all: bitrefill.com/esim/all-destinations. Locale listing and product pages: bitrefill.com/{country}/{lang}/esims/. Single product URLs follow `/{country}/{lang}/esims/bitrefill-esim-{destination-slug}/` (e.g. Japan, Global, Taiwan).

**Important:**
- **Data only:** No voice/SMS; data only.
- **Durations:** e.g. 1, 7, 15, 30 days; data caps vary (e.g. 1GB to unlimited).
- **Regional plans:** Some plans cover multiple countries (e.g. Europe, Asia).
- **Activation:** QR code provided after purchase; install eSIM before or during travel. Compatible with most modern smartphones (e.g. iPhone XS+, recent Android). See references/use-and-activate.md.

---

## Bitcoin & Lightning Services

**What they are:** Services for Bitcoin and Lightning Network users (e.g. channel opening, liquidity, payment tools).

**On the site:** Relevant sections linked from the main site and product catalog. Less central than gift cards, top-ups, and eSIMs for typical “buy something” flows.

**When to mention:** If the user asks about paying with Bitcoin or Lightning, point to checkout options (see references/buy-and-checkout.md). If they ask specifically about Lightning channels or liquidity, direct them to the Bitcoin/Lightning sections on bitrefill.com.

---

## Account & Authentication

**What it is:** Signup, login, password reset, and account management on Bitrefill.

**On the site:** bitrefill.com/signup and bitrefill.com/login (no locale prefix on auth pages).

**When to mention:** If the user wants to create an account, log in, reset a password, access order history, or use the referral program. See references/account-and-auth.md for full details.