bitrefill-website

浏览和探索 Bitrefill (bitrefill.com)：发现礼品卡、移动充值和 eSIM；按品牌、类别或国家/地区搜索；比较产品和面额；了解定价、供货情况以及每种产品类型的工作原理。当用户提到 Bitrefill、礼品卡、手机充值或 eSIM 旅行时使用。

# 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.) |

---

## 中文说明

# Bitrefill 网站技能

当用户想要**探索** Bitrefill (bitrefill.com) 时使用本技能：了解产品、搜索、比较，或理解定价与供货情况。Bitrefill 销售数字商品（礼品卡、移动充值、eSIM），并提供 Bitcoin/Lightning 服务。所有产品均以数字方式交付。

> **程序化访问与购买：** 若要通过 API 搜索、购买产品、管理订单或进行任何自动化工作流，请改用 **bitrefill-cli** 技能。本技能仅供浏览——帮助用户导航和理解网站。

## 何时使用本技能

在以下情况下激活：用户

- 提到 **Bitrefill** 或 bitrefill.com
- 询问如何在 Bitrefill 上**搜索**、**查找**或**比较**产品
- 需要**信息**（定价、供货、国家/地区限制、面额）
- 想了解 Bitrefill 提供什么或某种产品类型如何运作

当用户想要执行以下操作时，**重定向到 bitrefill-cli**：

- **购买**产品、下单或用加密货币付款
- 以程序化方式使用 Bitrefill **API** 或 **MCP 端点**
- 管理**订单**或**发票**
- 执行任何**自动化**或**基于 CLI** 的工作流

如果请求含糊（例如"我需要一份礼物"），请询问产品类型以及送给谁（国家/地区/兴趣）。

## 快速决策：用户想做什么？

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

## 产品类型一览

| 产品类型 | 是什么 | 主要 URL | 需要时加载详情 |
|--------------|------------|----------|---------------------------|
| **礼品卡** | 数字礼品卡（购物、流媒体、游戏、餐饮、旅行） | bitrefill.com/{country}/{lang}/gift-cards/ | references/product-types.md, references/supported-categories.md |
| **移动充值** | 为手机号充值预付费话费/流量（200+ 国家/地区） | bitrefill.com/refill/ | references/product-types.md |
| **eSIM** | 旅行数据套餐（仅数据、二维码激活、190+ 国家/地区） | bitrefill.com/esim/all-destinations or bitrefill.com/{country}/{lang}/esims/ | references/product-types.md |
| **Bitcoin / Lightning** | 通道开通、流动性、支付工具 | bitrefill.com (relevant sections) | references/product-types.md (brief) |
| **账户与认证** | 注册、登录、密码重置、推荐计划 | bitrefill.com/signup, /login | references/account-and-auth.md |

**关键：** 许多产品**因国家或地区而异**。在推荐产品或流程之前，务必确认或推断用户的国家/地区（对于充值，还有运营商）。

- **URL 中的国家/地区：** 路径的第一段是**国家/地区**，第二段是**语言**（例如 `/us/en/gift-cards/`、`/mx/es/gift-cards/`）。国家/地区段会将**显示的库存**过滤为可在该国家/地区使用的礼品卡。要查看某个特定国家/地区的库存，请在 URL 中使用该国家/地区。
- **地理锁定：** 可购买性是在 **IP 层级**强制执行的，而非由 URL 决定。如果某个产品无法购买，原因是用户的 IP/位置，而非 URL 中选择的国家/地区。

## 任务流程（高层）

### 浏览或搜索

1. 确定**产品类型**（礼品卡/充值/eSIM）和*