Bitrefill CLI
Search, purchase, and deliver digital goods (gift cards, mobile top-ups, eSIMs) via the Bitrefill CLI.
Requirements
- - A Bitrefill account is required to use this skill. Authentication is done via the Bitrefill API key or OAuth. See 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 INLINECODE1
- -
balance — Instant fulfillment, no on-chain wait. User pre-funds at 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, INLINECODE8ethereum — Ethereum mainnet (ETH) — address, paymentUri, INLINECODE12eth_base — Base (8453), native ETHusdc_base — Base (8453), USDCusdc_arbitrum — Arbitrum (42161), USDCusdc_polygon — Polygon (137), USDCusdc_erc20 — Ethereum (1), USDCusdc_solana — Solana, USDCusdt_polygon — Polygon (137), USDTusdt_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
CODEBLOCK0
From source: INLINECODE24
Auth
Generate an API key at bitrefill.com/account/developers:
CODEBLOCK1
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 |
|---|
| INLINECODE27 | Headless auth (skips OAuth) |
Core Workflow
CODEBLOCK2
1. Search
CODEBLOCK3
INLINECODE28 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
CODEBLOCK4
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
INLINECODE56 must be a JSON array [...], even for a single item.
CODEBLOCK5
Response includes invoice_id, payment_link, and x402_payment_url.
Max 15 items per call.
4. Track
CODEBLOCK6
Critical Gotchas
cart_items must be array, not object:
CODEBLOCK7
Use package_value after <&>, not the compound key:
CODEBLOCK8
Named/duration package_id must be exact, case-sensitive:
CODEBLOCK9
Country codes must be uppercase Alpha-2:
CODEBLOCK10
References
Load when needed:
Payment methods list, x402 protocol, response fields |
|
troubleshooting | Errors beyond the critical gotchas above |
Bitrefill CLI
通过 Bitrefill CLI 搜索、购买和交付数字商品（礼品卡、手机充值、eSIM）。
要求
- - 使用此技能需要拥有 Bitrefill 账户。通过 Bitrefill API 密钥或 OAuth 进行身份验证。详见设置。
- 需要加密钱包来发送加密货币或支付至 x402 端点（Base 网络上的 USDC）。此技能不提供钱包。
- 建议使用浏览器使用MCP 或 CLI，让代理在品牌网站上兑换代码，以实现完全自主的购物体验。此技能不提供此功能。
支持的支付方式
实现即时代理支付的最佳体验是使用 balance 的商店余额，其次是通过 x402 使用 Base 网络上的 USDC，然后是闪电网络。所有其他加密货币支付需要代理轮询发票状态以确认支付。
CLI 通过 bitrefill buy-products --help 返回完整列表。
- - balance — 即时完成，无需链上等待。用户在 bitrefill.com 预充值。自然消费上限。
- usdcbase 配合 x402 — 使用 --returnpaymentlink true（默认）获取 x402paymenturl。支持 x402 的代理可通过 Base 网络自主完成支付。
- lightning — 闪电网络 — lightningInvoice、satoshiPrice
- ethereum — 以太坊主网（ETH）— address、paymentUri、altcoinPrice
- ethbase — Base（8453），原生 ETH
- usdcbase — Base（8453），USDC
- usdcarbitrum — Arbitrum（42161），USDC
- usdcpolygon — Polygon（137），USDC
- usdcerc20 — 以太坊（1），USDC
- usdcsolana — Solana，USDC
- usdtpolygon — Polygon（137），USDT
- usdterc20 — 以太坊（1），USDT
- --returnpaymentlink true 选项返回的结账页面中提供支付卡、本地支付方式和其他加密货币支付方式。
消费保障
此技能支持真实货币交易。支付确认后，购买将立即完成。
- - 默认：购买前始终确认。 展示产品、面额、价格和支付方式；等待明确批准后再执行 buy-products。仅当用户明确选择当前会话时，才允许自主购买。
- 数字商品交付后，仅在无法正常使用时才可退款。根据欧盟消费者权利，礼品卡代码等数字商品不适用 14 天无理由退货政策。
- 礼品卡代码可视为现金等价物，应安全存储，不得公开分享。只有代理所有者才能访问代码。建议对代码使用加密数据存储，而非纯文本。
- 尽可能避免重写数字代码。如有可能，在代码兑换前优先使用内存存储，并仅在此时以编程方式访问和使用。
- 如果用户索要代码，请返回代码，但建议他们安全存储、不要公开分享，并尽快使用。
- 使用专用、余额有限的账户——切勿让代理访问高余额账户。
- 服务条款： https://www.bitrefill.com/terms/ 包含有关退款政策和购买限制的重要信息。
- 记录每次购买： invoice_id、产品、金额、支付方式。
- 非钱包： 此技能不是钱包。它是在 Bitrefill 上购买产品的工具。不负责存储私钥或管理您的加密钱包。
- 浏览器使用： 尝试在品牌网站上兑换代码时，反机器人保护机制可能会阻止代理。在这种情况下，询问用户是否希望手动完成兑换流程，如果是，则将代码返回给用户。
设置
安装
bash
npm install -g @bitrefill/cli
从源码安装：git clone https://github.com/bitrefill/cli.git && cd cli && pnpm install && pnpm build && npm link
身份验证
在 bitrefill.com/account/developers 生成 API 密钥：
bash
export BITREFILLAPIKEY=YOURAPIKEY
替代方案：在未设置 API 密钥的情况下运行任何命令，以触发基于浏览器的 OAuth。令牌存储在 ~/.config/bitrefill-cli/api.bitrefill.com.json。使用 bitrefill logout 清除。
环境变量
| 变量 | 用途 |
|---|
| BITREFILLAPIKEY | 无头身份验证（跳过 OAuth） |
核心工作流程
search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
1. 搜索
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 必须为大写 Alpha-2 ISO 代码（US、IT、BR）。--product_type：giftcard 或 esim（单数）。
发现类别： 使用 --query * 搜索——响应中包含 categories 数组，包含 slug 和计数（例如 food、games、streaming）。添加 --country 可查看特定国家/地区可用的类别。将这些 slug 用作 --category 值。
2. 获取详情
bash
bitrefill get-product-details --product_id steam-usa
返回 packages 数组。每个条目包含 packagevalue——将其用作 buy-products 中的 packageid。
忽略复合键，如 steam-usa<&>5——仅使用 <&> 之后的值。
三种面额类型：
- - 数字型： 5、50、200（作为数字传递）
- 时长型： 1 Month、12 Months（精确字符串，区分大小写）
- 命名型： 1GB, 7 Days、PUBG New State 300 NC（精确字符串，区分大小写）
仅接受 get-product-details 返回的值——任意金额将被拒绝。
3. 购买
--cart_items 必须为 JSON 数组 [...]，即使只有一个商品。
bash
数字型
bitrefill buy-products \
--cart
items [{productid: steam-usa, package_id: 5}] \
--payment
method usdcbase
时长型
bitrefill buy-products \
--cart
items [{productid: spotify-usa, package_id: 1 Month}] \
--payment_method balance
命名型（eSIM）
bitrefill buy-products \
--cart
items [{productid: bitrefill-esim-europe, package_id: 1GB, 7 Days}] \
--payment
method usdcbase
响应包含 invoiceid、paymentlink 和 x402paymenturl。
每次调用最多 15 个商品。
4. 追踪
bash
bitrefill get-invoice-by-id --invoice_id UUID
bitrefill list-orders --includeredemptioninfo true
关键注意事项
cart_items 必须是数组，而非对象：
bash
错误
--cart
items {productid: steam-usa, package_id: 5}
正确
--cart
items [{productid: steam-usa, package_id: 5}]
使用 <&> 之后的 package_value，而非复合键：
bash
错误：steam-usa<&>5 → 正确：5
命名型/时长型 package_id 必须精确，区分大小写：
bash
错误：1GB → 正确：1GB, 7 Days
错误：300 nc → 正确：PUBG New State 300 NC
国家代码必须为大写 Alpha-2：
bash
错误：us、USA、United States → 正确：US
参考资料
需要时加载：
支付
