npx skills add https://github.com/bitrefill/agents --skill bitrefill-cli智能体无法在亚马逊购物、预订爱彼迎或支付 Spotify 订阅费用——传统电子商务需要浏览器、验证码和信用卡。Bitrefill CLI 弥合了这一差距:它让智能体能够自主搜索、购买和交付来自 180 多个国家、1500 多个品牌的数字商品(礼品卡、手机充值、eSIM),并使用加密货币或预存账户余额支付——无需人工结账。
该 CLI 连接到 Bitrefill MCP 服务器 并动态发现可用工具,将每个工具作为带有类型化选项的子命令公开。结合 Base 网络上的 x402 支付,它实现了完全自主的智能体商务。
此技能涉及真实货币交易。 购买一旦交付即会立即完成,且不可退款。在启用自主购买功能之前,智能体和操作员必须了解相关要求和风险。
| 要求 | 位置 / 变量 | 用途 |
|---|---|---|
| Bitrefill OAuth 令牌 | ~/.config/bitrefill-cli/api.bitrefill.com.json | 针对用户的 Bitrefill 账户验证 CLI 请求 |
| Bitrefill 账户 | bitrefill.com/signup | 所有操作(搜索、购买、订单历史)必需 |
| (如果使用 ) |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
usdc_base| 智能体特定 (例如签名密钥、钱包 SDK) |
| 在 Base 网络上签名并提交链上 USDC 支付 |
预存账户余额 (如果使用 balance) | 在 bitrefill.com 充值 | 使用存储的账户余额支付购买 |
MCP_URL 环境变量 (可选) | 环境变量 | 覆盖默认 MCP 端点 (https://api.bitrefill.com/mcp) |
默认的 OAuth 流程会打开浏览器进行交互式授权——这需要人工进行初始设置。对于自主或无头环境:
~/.config/bitrefill-cli/api.bitrefill.com.json。~/.config/bitrefill-cli/api.bitrefill.com.json)。bitrefill list-orders --limit 1 —— 如果它返回时没有提示授权,则令牌有效。切勿将凭证提交到版本控制系统。 将
~/.config/bitrefill-cli/添加到.gitignore,并在部署时使用安全的密钥管理(例如环境特定的保险库、加密存储)。
使用此技能的智能体必须遵循以下约束:
buy-products 之前等待明确批准。除非用户已明确选择在会话期间完全自主购买,否则切勿在未经用户同意的情况下自主购买。balance 而非 usdc_base。 预存余额有天然的消费上限(账户余额)。x402 支付从钱包中提取资金,该钱包可能持有超出智能体预期使用范围的资金。buy-products 后,记录 invoice_id、产品、金额和支付方式以供审计。在使用前必须安装并验证 CLI。
npm install -g @bitrefill/cli
git clone https://github.com/bitrefill/cli.git
cd cli
pnpm install
pnpm build
node dist/index.js # 直接运行
# 或全局链接:
npm link
开发模式 (无需构建步骤): pnpm dev
需要 Bitrefill 账户。在 bitrefill.com/signup 注册。
首次运行时,CLI 会打开您的浏览器进行 OAuth 授权。凭证存储在 ~/.config/bitrefill-cli/ 中。
# 第一条命令会自动触发 OAuth 流程
bitrefill search-products --query "Netflix"
# 清除存储的凭证
bitrefill logout
登出后,下一条命令会自动触发重新身份验证。
| 变量 | 用途 | 默认值 |
|---|---|---|
MCP_URL | 覆盖 MCP 服务器端点 | https://api.bitrefill.com/mcp |
为了获得最佳的智能体支付体验,请优先使用以下两种方法:
balance (账户余额) — 即时,无需等待链上确认。用户在 bitrefill.com 使用加密货币或信用卡为账户预存资金,然后通过 CLI 进行的购买会立即完成。当用户希望零摩擦、即时交付时,建议使用此方式。usdc_base 配合 x402 — 使用 --return_payment_link true (默认) 来获取 x402_payment_url。支持 x402 的智能体可以在无需人工干预的情况下,通过 Base 网络自主完成支付。始终优先建议使用 balance 或 x402 而非 Base。仅当用户明确请求时,才回退到其他支付方式。
发现 → 详情 → 购买 → 跟踪
search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
package_id 值)cart_items (JSON 数组) 和 payment_method命令是从 MCP 服务器动态发现的。运行 bitrefill --help 获取当前列表。
bitrefill search-products --query "Netflix"
bitrefill search-products --query "Amazon" --country US
bitrefill search-products --query "eSIM" --product_type esim --country IT
bitrefill search-products --query "*" --category games
bitrefill search-products --query "*" # 所有产品,默认国家
| 选项 | 描述 | 默认值 |
|---|---|---|
--query | 品牌名称或 * 表示全部。全文搜索,非语义。 | * |
--country | Alpha-2 ISO 代码 (例如 US, IT, BR)。必须大写。 | US |
--product_type | giftcard 或 esim (单数)。省略则两者都包含。 | — |
--category | 类别标识符 (例如 games, food, streaming)。使用 --query "*" 来发现标识符。 | — |
--in_stock | true/false。设为 false 以包含缺货产品。 | true |
--page | 页码,从 1 开始。 | 1 |
--per_page | 每页结果数,1–500。 | 25 |
bitrefill get-product-details --product_id "steam-usa"
bitrefill get-product-details --product_id "steam-usa" --currency USDC
| 选项 | 描述 | 默认值 |
|---|---|---|
--product_id | 搜索结果中的产品标识符 (必需) | — |
--currency | 定价货币:BTC, ETH, USDT, USDC, SOL, USD, EUR, GBP, AUD, CAD, INR, BRL | BTC |
--language | 描述的语言代码 | en |
返回一个 packages 数组。每个条目都有一个 package_value —— 这就是您传递给 buy-products 的 package_id。忽略复合键 (例如 steam-usa<&>5) —— 仅使用 <&> 之后的值。
产品使用三种面额类型:
| 类型 | 示例产品 | package_value 示例 | 使用的 package_id |
|---|---|---|---|
| 数字型 | Steam USD, Amazon, Zalando | "5", "50", "200" | 5, 50, 200 (数字) |
| 时长型 | Spotify, 订阅服务 | "1 Month", "12 Months" | "1 Month" (精确字符串) |
| 命名型 | PUBG, eSIMs | "PUBG New State 300 NC", "1GB, 7 Days" | "PUBG New State 300 NC" (精确字符串) |
命名型/时长型 package_id 值区分大小写且必须完全匹配——部分匹配 (例如 "1GB" 而不是 "1GB, 7 Days") 会被拒绝。仅接受 get-product-details 列出的值;不支持任意金额。
--cart_items 必须是一个 JSON 数组,即使对于单个商品也是如此。
# 数字面额
bitrefill buy-products \
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
--payment_method usdc_base
# 命名面额 (eSIM 数据套餐)
bitrefill buy-products \
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]' \
--payment_method usdc_base
# 时长面额 (订阅)
bitrefill buy-products \
--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]' \
--payment_method usdc_base
# 多个商品 (最多 15 个)
bitrefill buy-products \
--cart_items '[{"product_id": "steam-usa", "package_id": 10}, {"product_id": "netflix-usa", "package_id": 25}]' \
--payment_method bitcoin
# 原始加密货币详情 (无支付链接)
bitrefill buy-products \
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
--payment_method usdc_base \
--return_payment_link false
| 选项 | 描述 | 默认值 |
|---|---|---|
--cart_items | {product_id, package_id} 对象的 JSON 数组。1–15 个商品。(必需) | — |
--payment_method | 参见下面的支付方式表。(必需) | — |
--return_payment_link | true → payment_link + x402_payment_url。false → 原始 address/paymentUri。 | true |
响应字段 (当 return_payment_link true 时):
invoice_id — 与 get-invoice-by-id 一起使用以轮询状态payment_link — 浏览器结账 URLx402_payment_url — 程序化的 x402 支付端点payment_info.address — 链上目标地址payment_info.paymentUri — 包含合约和金额的 EIP-681 URIpayment_info.altcoinPrice — 支付代币的金额bitrefill list-invoices
bitrefill list-invoices --only_paid false --limit 10
bitrefill list-invoices --after "2026-03-01T00:00:00Z" --before "2026-03-10T00:00:00Z"
| 选项 | 描述 | 默认值 |
|---|---|---|
--limit | 1–50 | 25 |
--start | 分页偏移量 | 0 |
--after | ISO 8601 日期过滤器 | — |
--before | ISO 8601 日期过滤器 | — |
--only_paid | true 隐藏未支付的发票 | true |
--include_orders | 包含订单详情 | true |
bitrefill get-invoice-by-id --invoice_id "27713c64-6715-48d8-95ef-45eed23efef7"
| 选项 | 描述 | 默认值 |
|---|---|---|
--invoice_id | 发票的 UUID (必需) | — |
--include_orders | 包含订单详情 | true |
--include_redemption_info | 包含兑换码/链接 | false |
--include_access_token | 包含未经验证的访问令牌 | false |
bitrefill list-orders
bitrefill list-orders --limit 5 --include_redemption_info true
| 选项 | 描述 | 默认值 |
|---|---|---|
--limit | 1–50 | 25 |
--start | 分页偏移量 | 0 |
--after / --before | ISO 8601 日期过滤器 | — |
--include_redemption_info | 包含兑换码/链接 | false |
bitrefill get-order-by-id --order_id "69af584e8a2639d14ac35e96"
如果订单已解封 (已支付并交付),则返回兑换码或链接。
| 选项 | 描述 | 默认值 |
|---|---|---|
--order_id | 订单 ID (必需) | — |
--include_redemption_info | 包含兑换码/链接 | true |
bitrefill logout
从 ~/.config/bitrefill-cli/ 删除存储的 OAuth 凭证。
| 方式 | 链 / 资产 |
|---|---|
bitcoin | Bitcoin (SegWit) — 返回 address, BIP21, lightningInvoice, satoshiPrice |
lightning | Lightning — 返回 lightningInvoice, satoshiPrice |
ethereum | Ethereum 主网 (ETH) — 返回 address, paymentUri, altcoinPrice |
eth_base | Base (8453), 原生 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 账户余额 — 无地址,从余额中支付 |
--return_payment_link false — 原始支付详情:address, amount, paymentUri (对于 Bitcoin 还有 lightningInvoice)。用于钱包/程序化支付。响应中无 payment_link 或 x402_payment_url。--return_payment_link true (默认) — 返回 payment_link (浏览器结账) 和 x402_payment_url (程序化支付),以及 原始 payment_info。x402 支持基于 HTTP 402 的加密货币支付。GET x402_payment_url → 接收 402 状态码及支付指令 (Base64 JSON: 金额, payTo, 网络, 超时) → 发送加密货币 → 使用证明重新提交。适用于智能体/自动化工具;人工使用 payment_link。
cart_items: 期望数组,收到对象--cart_items 必须是一个 JSON 数组 [...],即使对于单个商品也是如此。README 示例显示了一个对象 {} —— 那是无效的。
# 错误 — 对象
--cart_items '{"product_id": "steam-usa", "package_id": 5}'
# 正确 — 对象数组
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
get-product-details 的输出显示复合 ID,如 steam-usa<&>5。不要使用复合键 —— 仅使用 <&> 之后的值。
# 错误 — 复合键
--cart_items '[{"product_id": "steam-usa", "package_id": "steam-usa<&>5"}]'
# 正确 — 数字值
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
对于命名面额,请使用精确的完整字符串。常见错误:
# 错误 — 对命名套餐使用数字猜测
--cart_items '[{"product_id": "spotify-usa", "package_id": 1}]'
# 正确
--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]'
# 错误 — 部分匹配
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB"}]'
# 正确
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]'
# 错误 — 大小写错误
--cart_items '[{"product_id": "pubg-new-state-international", "package_id": "PUBG New State 300 nc"}]'
# 正确
--cart_items '[{"product_id": "pubg-new-state-international", "package_id": "PUBG New State 300 NC"}]'
仅接受 get-product-details 列出的值。任意金额 (例如 7, 15, 25) 会被拒绝。
由无效的 --country 值引起:
us 而不是 US) — 静默失败USA 而不是 US) — 失败United States) — 失败ZZ) — 失败--page -1) — 失败修复:始终使用大写的 Alpha-2 ISO 代码 (US, IT, BR, GB)。
CLI 在发送到服务器之前在客户端验证枚举值。
| 选项 | 有效值 | 常见错误 |
|---|---|---|
--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 (区分大小写) |
--product_type | giftcard, esim | giftcards (复数), gift_card, sim |
省略必需的 --cart_items 或 --product_id 时,会以以下错误退出:error: required option '--<name> <value>' not specified。CLI 在连接到服务器之前强制执行必需选项。
每次 buy-products 调用最多 15 个商品。服务器拒绝并显示:Too big: expected array to have <=15 items。
per_page 超过 500服务器拒绝:per_page must be less than 500。
--cart_items 中的 JSON 格式错误非 JSON 字符串会崩溃并显示:Unexpected token ... is not valid JSON。确保值是有效的 JSON。Shell 引号很重要 —— 在 JSON 周围使用单引号,内部使用双引号。
package_id从购物车商品对象中省略 package_id 会导致:Invalid denomination 'undefined'。每个商品都需要 product_id 和 package_id。
get-invoice-by-id 使用不存在的 ID:Invoice not found (RESOURCE_NOT_FOUND)buy-products 使用不存在的 product_id:Product '<slug>' is not available (RESOURCE_NOT_FOUND)通过 search-products 验证标识符,通过 list-invoices 验证发票 ID。
MCP_URL将 MCP_URL 设置为非 Bitrefill 端点会产生 StreamableHTTPError 并包含远程服务器的 HTML 正文。取消设置该变量或将其指向 https://api.bitrefill.com/mcp。
如果 CLI 在启动时挂起或失败:
bitrefill logout 以清除过期的凭证~/.config/bitrefill-cli/api.bitrefill.com.jsonfound: 0 且无错误通常意味着:
--category 标识符不存在 (无错误,只是空结果)--country 中不可用--in_stock true (默认) 过滤掉了暂时缺货的产品尝试放宽条件:移除 --category,更改 --country,或设置 --in_stock false。
默认情况下 list-invoices 仅显示已支付的发票。要查看所有 (包括待处理/已过期的):--only_paid false。
发票在 180 分钟后过期。如果未支付,请创建新的发票 —— 您无法重新支付已过期的发票。
每周安装量
0
代码仓库
GitHub 星标数
2
首次出现
1970年1月1日
安全审计
Agents can't shop on Amazon, book an Airbnb, or pay for a Spotify subscription — traditional e-commerce requires browsers, CAPTCHAs, and credit cards. The Bitrefill CLI bridges this gap: it lets agents autonomously search, purchase, and deliver digital goods (gift cards, mobile top-ups, eSIMs) from 1,500+ brands across 180+ countries, paying with crypto or pre-funded store credits — no human checkout required.
The CLI connects to the Bitrefill MCP server and dynamically discovers available tools, exposing each as a subcommand with typed options. Combined with x402 payments over Base, it enables fully autonomous agent commerce.
Source: github.com/bitrefill/cli
This skill enables real-money transactions. Purchases are fulfilled instantly and are non-refundable once delivered. Agents and operators must understand the requirements and risks before enabling autonomous purchasing.
| Requirement | Location / Variable | Purpose |
|---|---|---|
| Bitrefill OAuth token | ~/.config/bitrefill-cli/api.bitrefill.com.json | Authenticates CLI requests against the user's Bitrefill account |
| Bitrefill account | bitrefill.com/signup | Required for all operations (search, buy, order history) |
x402-capable wallet (if using usdc_base) | Agent-specific (e.g. signing key, wallet SDK) | Signs and submits on-chain USDC payments on Base |
Pre-funded account balance (if using balance) | Funded at bitrefill.com | Pays for purchases from stored account credits |
MCP_URL env var (optional) | Environment variable | Overrides the default MCP endpoint (https://api.bitrefill.com/mcp) |
The default OAuth flow opens a browser for interactive authorization — this requires a human for initial setup. For autonomous or headless environments:
~/.config/bitrefill-cli/api.bitrefill.com.json.~/.config/bitrefill-cli/api.bitrefill.com.json).bitrefill list-orders --limit 1 — if it returns without prompting for auth, the token is valid.Never commit credentials to version control. Add
~/.config/bitrefill-cli/to.gitignoreand use secure secret management (e.g. environment-specific vaults, encrypted storage) for deployment.
Agents using this skill must follow these constraints:
buy-products. Never purchase autonomously without user consent unless the user has explicitly opted into fully autonomous purchasing for the session.balance over usdc_base for autonomous agents. Pre-funded balance has a natural spending cap (the account balance). x402 payments draw from a wallet that may hold more funds than intended for agent use.buy-products call, log the invoice_id, product, amount, and payment method for audit.The CLI must be installed and authenticated before use.
npm install -g @bitrefill/cli
git clone https://github.com/bitrefill/cli.git
cd cli
pnpm install
pnpm build
node dist/index.js # run directly
# or link globally:
npm link
Dev mode (no build step): pnpm dev
Requires a Bitrefill account. Sign up at bitrefill.com/signup.
On first run, the CLI opens your browser for OAuth authorization. Credentials are stored in ~/.config/bitrefill-cli/.
# First command triggers OAuth flow automatically
bitrefill search-products --query "Netflix"
# Clear stored credentials
bitrefill logout
After logout, the next command triggers re-authentication automatically.
| Variable | Purpose | Default |
|---|---|---|
MCP_URL | Override MCP server endpoint | https://api.bitrefill.com/mcp |
For the best agentic payments experience, prefer these two methods:
balance (store credits) — Instant, no on-chain confirmation wait. The user pre-funds their account at bitrefill.com with crypto or card, then purchases via CLI are fulfilled immediately. Suggest this when the user wants zero-friction, instant delivery.usdc_base with x402 — Use --return_payment_link true (default) to get an x402_payment_url. An x402-capable agent can autonomously complete the payment over Base without human intervention.Always suggest balance or x402 over Base first. Fall back to other payment methods only if the user explicitly requests them.
Discovery → Details → Purchase → Track
search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
package_id values)cart_items (JSON array) and payment_methodCommands are discovered dynamically from the MCP server. Run bitrefill --help for the current list.
bitrefill search-products --query "Netflix"
bitrefill search-products --query "Amazon" --country US
bitrefill search-products --query "eSIM" --product_type esim --country IT
bitrefill search-products --query "*" --category games
bitrefill search-products --query "*" # all products, default country
| Option | Description | Default |
|---|---|---|
--query | Brand name or * for all. Fulltext, not semantic. | * |
--country | Alpha-2 ISO code (e.g. US, IT, BR). Must be uppercase. | US |
bitrefill get-product-details --product_id "steam-usa"
bitrefill get-product-details --product_id "steam-usa" --currency USDC
| Option | Description | Default |
|---|---|---|
--product_id | Product slug from search results (required) | — |
--currency | Pricing currency: BTC, ETH, USDT, USDC, SOL, USD, EUR, , , , , |
Returns a packages array. Each entry has a package_value — this is what you pass as package_id to buy-products. Ignore the compound key (e.g. steam-usa<&>5) — use only the value after <&>.
Products use three denomination types:
| Type | Example product | package_value examples | package_id to use |
|---|---|---|---|
| Numeric | Steam USD, Amazon, Zalando | "5", "50", "200" | 5, 50, 200 (number) |
Named/duration package_id values are case-sensitive and must match exactly — partial matches (e.g. "1GB" instead of "1GB, 7 Days") are rejected. Only values listed by get-product-details are accepted; arbitrary amounts are not supported.
--cart_items must be a JSON array, even for a single item.
# Numeric denomination
bitrefill buy-products \
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
--payment_method usdc_base
# Named denomination (eSIM data plan)
bitrefill buy-products \
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]' \
--payment_method usdc_base
# Duration denomination (subscription)
bitrefill buy-products \
--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]' \
--payment_method usdc_base
# Multiple items (max 15)
bitrefill buy-products \
--cart_items '[{"product_id": "steam-usa", "package_id": 10}, {"product_id": "netflix-usa", "package_id": 25}]' \
--payment_method bitcoin
# Raw crypto details (no payment link)
bitrefill buy-products \
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \
--payment_method usdc_base \
--return_payment_link false
| Option | Description | Default |
|---|---|---|
--cart_items | JSON array of {product_id, package_id} objects. 1–15 items. (required) | — |
--payment_method | See payment methods table below. (required) | — |
--return_payment_link | true → payment_link + x402_payment_url. → raw /. |
Response fields (whenreturn_payment_link true):
invoice_id — use with get-invoice-by-id to poll statuspayment_link — browser checkout URLx402_payment_url — programmatic x402 payment endpointpayment_info.address — on-chain destinationpayment_info.paymentUri — EIP-681 URI with contract + amountpayment_info.altcoinPrice — amount in payment tokenbitrefill list-invoices
bitrefill list-invoices --only_paid false --limit 10
bitrefill list-invoices --after "2026-03-01T00:00:00Z" --before "2026-03-10T00:00:00Z"
| Option | Description | Default |
|---|---|---|
--limit | 1–50 | 25 |
--start | Pagination offset | 0 |
--after | ISO 8601 date filter | — |
--before | ISO 8601 date filter | — |
bitrefill get-invoice-by-id --invoice_id "27713c64-6715-48d8-95ef-45eed23efef7"
| 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 |
bitrefill list-orders
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 |
bitrefill get-order-by-id --order_id "69af584e8a2639d14ac35e96"
Returns redemption code or 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 |
bitrefill logout
Deletes stored OAuth credentials from ~/.config/bitrefill-cli/.
| Method | Chain / Asset |
|---|---|
bitcoin | Bitcoin (SegWit) — returns address, BIP21, lightningInvoice, satoshiPrice |
lightning | Lightning — returns lightningInvoice, satoshiPrice |
ethereum |
--return_payment_link false — raw payment details: address, amount, paymentUri (+ lightningInvoice for Bitcoin). For wallet/programmatic pay. No payment_link or x402_payment_url in response.--return_payment_link true (default) — returns payment_link (browser checkout) and x402_payment_url (programmatic pay), raw .x402 enables HTTP 402-based crypto payments. GET x402_payment_url → receive 402 + payment instructions (Base64 JSON: amount, payTo, networks, timeout) → send crypto → resubmit with proof. For agents/automated tools; humans use payment_link.
cart_items: expected array, received object--cart_items must be a JSON array [...], even for a single item. The README example shows an object {} — that does not work.
# WRONG — object
--cart_items '{"product_id": "steam-usa", "package_id": 5}'
# CORRECT — array of objects
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
The get-product-details output shows compound IDs like steam-usa<&>5. Do not use the compound key — use only the value after <&>.
# WRONG — compound key
--cart_items '[{"product_id": "steam-usa", "package_id": "steam-usa<&>5"}]'
# CORRECT — numeric value
--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
For named denominations , use the exact full string. Common mistakes:
# WRONG — numeric guess for a named package
--cart_items '[{"product_id": "spotify-usa", "package_id": 1}]'
# CORRECT
--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]'
# WRONG — partial match
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB"}]'
# CORRECT
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]'
# WRONG — wrong case
--cart_items '[{"product_id": "pubg-new-state-international", "package_id": "PUBG New State 300 nc"}]'
# CORRECT
--cart_items '[{"product_id": "pubg-new-state-international", "package_id": "PUBG New State 300 NC"}]'
Only values listed by get-product-details are accepted. Arbitrary amounts (e.g. 7, 15, 25) are rejected.
Caused by invalid --country values:
us instead of US) — silently failsUSA instead of US) — failsUnited States) — failsZZ) — fails--page -1) — failsFix: always use uppercase Alpha-2 ISO codes (US, IT, BR, GB).
The CLI validates enum values client-side before sending to the server.
| Option | Valid values | Common mistake |
|---|---|---|
--payment_method | bitcoin, ethereum, lightning, usdc_polygon, usdt_polygon, usdc_erc20, usdt_erc20, usdc_arbitrum, usdc_solana, , , |
Omitting --cart_items or --product_id when required exits with: error: required option '--<name> <value>' not specified. The CLI enforces required options before connecting to the server.
Maximum 15 items per buy-products call. Server rejects with: Too big: expected array to have <=15 items.
per_page exceeds 500Server rejects: per_page must be less than 500.
--cart_itemsNon-JSON strings crash with: Unexpected token ... is not valid JSON. Ensure the value is valid JSON. Shell quoting matters — use single quotes around the JSON, double quotes inside.
package_id in cart itemOmitting package_id from a cart item object results in: Invalid denomination 'undefined'. Both product_id and package_id are required per item.
get-invoice-by-id with a nonexistent ID: Invoice not found (RESOURCE_NOT_FOUND)buy-products with a nonexistent product_id: Product '<slug>' is not available (RESOURCE_NOT_FOUND)Verify slugs via search-products and invoice IDs via list-invoices.
MCP_URLSetting MCP_URL to a non-Bitrefill endpoint produces a StreamableHTTPError with the remote server's HTML body. Unset the variable or point it to https://api.bitrefill.com/mcp.
If the CLI hangs or fails on startup:
bitrefill logout to clear stale credentials~/.config/bitrefill-cli/api.bitrefill.com.jsonfound: 0 with no error typically means:
--category slug doesn't exist (no error, just empty results)--country--in_stock true (default) filters out products that are temporarily out of stockTry broadening: remove --category, change --country, or set --in_stock false.
By default list-invoices shows only paid invoices. To see all (including pending/expired): --only_paid false.
Invoices expire after 180 minutes. If unpaid, create a new one — you cannot re-pay an expired invoice.
Weekly Installs
0
Repository
GitHub Stars
2
First Seen
Jan 1, 1970
Security Audits
AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具
41,400 周安装
Three.js交互开发指南:Raycaster光线投射与鼠标点击检测实现3D交互
1,900 周安装
RivetKit React客户端:快速连接Rivet Actors的React应用开发工具
2,100 周安装
CRCHCN 代币技能 - 在 mbc-20 协议上操作 CRCHCN 代币的 Node.js 工具
RivetKit JavaScript客户端:快速构建连接Rivet Actors的浏览器与Node.js应用
2,100 周安装
高端实用极简主义UI架构师 | 文档风格网页设计 | 前端工程指令
3,000 周安装
SQL Pro 高级查询与性能优化指南 - CTE、窗口函数、执行计划分析
2,100 周安装
--product_type | giftcard or esim (singular). Omit for both. | — |
--category | Category slug (e.g. games, food, streaming). Use --query "*" to discover slugs. | — |
--in_stock | true/false. Set false to include out-of-stock. | true |
--page | Page number, 1-indexed. | 1 |
--per_page | Results per page, 1–500. | 25 |
GBPAUDCADINRBRLBTC |
--language | Language code for descriptions | en |
| Spotify, subscriptions |
"1 Month", "12 Months" |
"1 Month" (exact string) |
| Named | PUBG, eSIMs | "PUBG New State 300 NC", "1GB, 7 Days" | "PUBG New State 300 NC" (exact string) |
falseaddresspaymentUritrue |
--only_paidtrue hides unpaid invoices |
true |
--include_orders | Include order details | true |
false |
| Include redemption codes/links |
false |
Ethereum mainnet (ETH) — returns 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 — no address, paid from balance |
payment_infousdc_baseeth_basebalancepaypal, visa, USDC_BASE (case-sensitive) |
--product_type | giftcard, esim | giftcards (plural), gift_card, sim |