Back to Details

bitrefill-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bitrefill CLI — Real-World Spending for Agents

Bitrefill CLI — 面向Agent的真实场景消费

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
Agent无法在亚马逊购物、预订Airbnb或支付Spotify订阅费用——传统电子商务需要浏览器、验证码和信用卡。Bitrefill CLI填补了这一空白：它允许Agent在180多个国家/地区的1500+品牌中自主搜索、购买和交付数字商品（礼品卡、手机充值、eSIM卡），支持加密货币或预存账户余额支付——无需人工结账。
该CLI连接到Bitrefill MCP服务器，动态发现可用工具，并将每个工具作为带类型选项的子命令暴露出来。结合Base网络上的x402支付，它实现了完全自主的Agent商务。
来源：github.com/bitrefill/cli

Security & Autonomous Operation

安全与自主操作

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.
本技能支持真实货币交易。 购买会即时完成，交付后不可退款。Agent和操作者在启用自主购买功能前，必须了解相关要求和风险。

Required Credentials & Configuration

必要凭证与配置

RequirementLocation / VariablePurpose
Bitrefill OAuth token
~/.config/bitrefill-cli/api.bitrefill.com.json
Authenticates CLI requests against the user's Bitrefill account
Bitrefill accountbitrefill.com/signupRequired 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.comPays for purchases from stored account credits
MCP_URL
env var (optional)		Environment variableOverrides the default MCP endpoint (
https://api.bitrefill.com/mcp
)
要求位置 / 变量用途
Bitrefill OAuth令牌
~/.config/bitrefill-cli/api.bitrefill.com.json
验证CLI请求与用户Bitrefill账户的关联
Bitrefill账户bitrefill.com/signup所有操作（搜索、购买、订单历史）都需要
支持x402的钱包（若使用
usdc_base
）		Agent专属（如签名密钥、钱包SDK）在Base网络上签名并提交链上USDC支付
预充值账户余额（若使用
balance
）		在bitrefill.com充值从存储的账户余额中支付购买费用
MCP_URL
环境变量（可选）		环境变量覆盖默认MCP端点(
https://api.bitrefill.com/mcp
)

Provisioning Credentials for Autonomous Agents

为自主Agent配置凭证

The default OAuth flow opens a browser for interactive authorization — this requires a human for initial setup. For autonomous or headless environments:
  1. Run the OAuth flow once interactively on a machine with a browser. The CLI stores the token at 
    ~/.config/bitrefill-cli/api.bitrefill.com.json
    .
  2. Copy the credentials file to the autonomous agent's environment at the same path (
    ~/.config/bitrefill-cli/api.bitrefill.com.json
    ).
  3. Verify by running 
    bitrefill list-orders --limit 1
    — if it returns without prompting for auth, the token is valid.
  4. Token refresh: If the token expires, repeat step 1. Monitor for auth errors in the agent's logs and re-provision as needed.
Never commit credentials to version control. Add 
~/.config/bitrefill-cli/
to 
.gitignore
and use secure secret management (e.g. environment-specific vaults, encrypted storage) for deployment.
默认OAuth流程会打开浏览器进行交互式授权——这需要人工完成初始设置。对于自主或无头环境：
  1. 在带浏览器的机器上运行一次交互式OAuth流程。CLI会将令牌存储在
    ~/.config/bitrefill-cli/api.bitrefill.com.json
    。
  2. 将凭证文件复制到自主Agent环境的相同路径 (
    ~/.config/bitrefill-cli/api.bitrefill.com.json
    )。
  3. 验证：运行
    bitrefill list-orders --limit 1
    ——如果无需提示授权即可返回结果，说明令牌有效。
  4. 令牌刷新：如果令牌过期，重复步骤1。监控Agent日志中的授权错误，必要时重新配置。
切勿将凭证提交到版本控制系统。 将
~/.config/bitrefill-cli/
添加到
.gitignore
，并使用安全的密钥管理工具（如环境专属的密码库、加密存储）进行部署。

Spending Safeguards

消费安全措施

Agents using this skill must follow these constraints:
  • Always confirm with the user before purchasing. Present the product name, denomination, price, and payment method, and wait for explicit approval before calling 
    buy-products
    . Never purchase autonomously without user consent unless the user has explicitly opted into fully autonomous purchasing for the session.
  • Use a dedicated, limited-balance account. For autonomous operation, create a separate Bitrefill account funded with only the amount you're comfortable the agent spending. Do not give agents access to high-balance accounts.
  • Prefer 
    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.
  • Never store private keys in plain text. If using x402 payments, the signing wallet's private key must be managed through a secure key management system — not in environment variables, config files, or source code.
  • Log all purchases. After every 
    buy-products
    call, log the 
    invoice_id
    , product, amount, and payment method for audit.
使用本技能的Agent 必须遵守以下约束：
  • 购买前务必征得用户确认。展示产品名称、面额、价格和支付方式，等待用户明确批准后再调用
    buy-products
    。除非用户明确选择会话内完全自主购买，否则绝不能未经用户同意自主购买。
  • 使用专用的低余额账户。对于自主操作，创建单独的Bitrefill账户，仅存入你能接受Agent花费的金额。不要让Agent访问高余额账户。
  • 自主Agent优先使用
    balance
    而非
    usdc_base
    。预充值余额有天然的消费上限（账户余额）。x402支付会从钱包扣款，该钱包的资金可能远超Agent的预期使用额度。
  • 切勿明文存储私钥。如果使用x402支付，签名钱包的私钥必须通过安全的密钥管理系统管理——不能存储在环境变量、配置文件或源代码中。
  • 记录所有购买行为。每次调用
    buy-products
    后，记录
    invoice_id
    、产品、金额和支付方式，以便审计。

Prerequisites

前置条件

The CLI must be installed and authenticated before use.
使用前必须安装并验证CLI。

Installation

安装

From NPM (recommended)

从NPM安装（推荐）

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

From Source

从源代码安装

bash
git clone https://github.com/bitrefill/cli.git
cd cli
pnpm install
pnpm build
node dist/index.js    # run directly
bash
git clone https://github.com/bitrefill/cli.git
cd cli
pnpm install
pnpm build
node dist/index.js    # 直接运行

or link globally:

或全局链接：

npm link

Dev mode (no build step): `pnpm dev`
npm link

开发模式（无需构建步骤）：`pnpm dev`

Authentication

身份验证

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/
.
bash
undefined
需要Bitrefill账户。在bitrefill.com/signup注册。
首次运行时，CLI会打开浏览器进行OAuth授权。凭证存储在
~/.config/bitrefill-cli/
。
bash
undefined

First command triggers OAuth flow automatically

首次命令会自动触发OAuth流程

bitrefill search-products --query "Netflix"
bitrefill search-products --query "Netflix"

Clear stored credentials

清除存储的凭证

bitrefill logout

After logout, the next command triggers re-authentication automatically.
bitrefill logout

注销后，下一次命令会自动触发重新验证。

Environment

环境变量

VariablePurposeDefault
MCP_URL
Override MCP server endpoint
https://api.bitrefill.com/mcp
变量用途默认值
MCP_URL
覆盖MCP服务器端点
https://api.bitrefill.com/mcp

Recommended Payment for Agents

推荐的Agent支付方式

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.
为获得最佳的Agent支付体验，优先选择以下两种方式：
  • balance
    （账户余额）     — 即时到账，无需等待链上确认。用户在bitrefill.com用加密货币或银行卡预充值账户，然后通过CLI完成的购买会立即生效。当用户希望零摩擦、即时交付时，建议使用此方式。
  • 基于x402的
    usdc_base
     — 使用
    --return_payment_link true
    （默认值）获取
    x402_payment_url
    。支持x402的Agent可在Base网络上自主完成支付，无需人工干预。
始终优先推荐
balance
或Base网络上的x402支付。仅当用户明确要求时，才使用其他支付方式。

Core Workflow

核心工作流程

Discovery → Details → Purchase → Track
search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
  1. Search for a product by keyword, category, or country
  2. Get details to find available denominations (numeric 
    package_id
    values)
  3. Buy by specifying 
    cart_items
    (JSON array) and 
    payment_method
  4. Track via invoice ID or order listing
发现 → 详情 → 购买 → 追踪
search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
  1. 搜索：通过关键词、类别或国家查找产品
  2. 获取详情：查找可用面额（数字
    package_id
    值）
  3. 购买：指定
    cart_items
    （JSON 数组）和
    payment_method
  4. 追踪：通过发票ID或订单列表查看状态

Available Commands

可用命令

Commands are discovered dynamically from the MCP server. Run 
bitrefill --help
for the current list.
命令从MCP服务器动态发现。运行
bitrefill --help
获取当前命令列表。

search-products

search-products

bash
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
OptionDescriptionDefault
--query
Brand name or 
*
for all. Fulltext, not semantic.
*
--country
Alpha-2 ISO code (e.g. 
US
, 
IT
, 
BR
). Must be uppercase.
US
--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
bash
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
两位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

get-product-details

get-product-details

bash
bitrefill get-product-details --product_id "steam-usa"
bitrefill get-product-details --product_id "steam-usa" --currency USDC
OptionDescriptionDefault
--product_id
Product slug from search results (required)—
--currency
Pricing currency: 
BTC
, 
ETH
, 
USDT
, 
USDC
, 
SOL
, 
USD
, 
EUR
, 
GBP
, 
AUD
, 
CAD
, 
INR
, 
BRL
BTC
--language
Language code for descriptions
en
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:
TypeExample product
package_value
examples
package_id
to use
NumericSteam USD, Amazon, Zalando
"5"
, 
"50"
, 
"200"
5
, 
50
, 
200
(number)
DurationSpotify, subscriptions
"1 Month"
, 
"12 Months"
"1 Month"
(exact string)
NamedPUBG, eSIMs
"PUBG New State 300 NC"
, 
"1GB, 7 Days"
"PUBG New State 300 NC"
(exact string)
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.
bash
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美元礼品卡、亚马逊礼品卡、Zalando礼品卡
"5"
, 
"50"
, 
"200"
5
, 
50
, 
200
（数字）
时长型Spotify订阅、会员服务
"1 Month"
, 
"12 Months"
"1 Month"
（精确字符串）
命名型PUBG游戏道具、eSIM套餐
"PUBG New State 300 NC"
, 
"1GB, 7 Days"
"PUBG New State 300 NC"
（精确字符串）
命名型/时长型的
package_id
值区分大小写，必须完全匹配——部分匹配（如用
"1GB"
代替
"1GB, 7 Days"
）会被拒绝。仅接受
get-product-details
返回的值；不支持自定义金额。

buy-products

buy-products

--cart_items
must be a JSON array, even for a single item.
bash
undefined
--cart_items
必须是JSON数组，即使只有一个商品。
bash
undefined

Numeric denomination

数字型面额

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

Named denomination (eSIM data plan)

命名型面额（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": "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
bitrefill buy-products
--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]'
--payment_method usdc_base

Multiple items (max 15)

多件商品（最多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": 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`. `false` → raw `address`/`paymentUri`. | `true` |

**Response fields (when `return_payment_link true`):**
- `invoice_id` — use with `get-invoice-by-id` to poll status
- `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
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` — 浏览器结账URL
- `x402_payment_url` — 程序化x402支付端点
- `payment_info.address` — 链上收款地址
- `payment_info.paymentUri` — 包含合约和金额的EIP-681 URI
- `payment_info.altcoinPrice` — 支付代币的金额

list-invoices

list-invoices

bash
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"
OptionDescriptionDefault
--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
bash
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

get-invoice-by-id

get-invoice-by-id

bash
bitrefill get-invoice-by-id --invoice_id "27713c64-6715-48d8-95ef-45eed23efef7"
OptionDescriptionDefault
--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
bash
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

list-orders

list-orders

bash
bitrefill list-orders
bitrefill list-orders --limit 5 --include_redemption_info true
OptionDescriptionDefault
--limit
1–50
25
--start
Pagination offset
0
--after
/ 
--before
ISO 8601 date filters—
--include_redemption_info
Include redemption codes/links
false
bash
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

get-order-by-id

get-order-by-id

bash
bitrefill get-order-by-id --order_id "69af584e8a2639d14ac35e96"
Returns redemption code or link if the order is unsealed (paid and delivered).
OptionDescriptionDefault
--order_id
Order ID (required)—
--include_redemption_info
Include redemption codes/links
true
bash
bitrefill get-order-by-id --order_id "69af584e8a2639d14ac35e96"
如果订单已解锁（已支付并交付），返回兑换码或链接。
选项描述默认值
--order_id
订单ID（必填）—
--include_redemption_info
包含兑换码/链接
true

logout

logout

bash
bitrefill logout
Deletes stored OAuth credentials from 
~/.config/bitrefill-cli/
.
bash
bitrefill logout
从
~/.config/bitrefill-cli/
删除存储的OAuth凭证。

Payment

支付

Payment Methods

支付方式

MethodChain / Asset
bitcoin
Bitcoin (SegWit) — returns 
address
, 
BIP21
, 
lightningInvoice
, 
satoshiPrice
lightning
Lightning — returns 
lightningInvoice
, 
satoshiPrice
ethereum
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
方式链 / 资产
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账户余额——无收款地址，从账户余额扣款

Response Modes

响应模式

  • --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), plus raw 
    payment_info
    .
  • --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 Protocol

x402协议

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
.
x402 基于HTTP 402实现加密货币支付。
GET x402_payment_url
→ 收到402响应 + 支付指令（Base64编码的JSON：金额、
payTo
、网络、超时）→ 发送加密货币 → 提交支付凭证。适用于Agent/自动化工具；人类用户使用
payment_link
。

Troubleshooting

故障排除

cart_items
: expected array, received object

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.
bash
undefined
--cart_items
必须是JSON数组 
[...]
，即使只有一个商品。README示例中的对象
{}
无法正常工作。
bash
undefined

WRONG — object

错误示例 — 对象格式

--cart_items '{"product_id": "steam-usa", "package_id": 5}'
--cart_items '{"product_id": "steam-usa", "package_id": 5}'

CORRECT — array of objects

正确示例 — 对象数组格式

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

Invalid denomination

无效面额

The 
get-product-details
output shows compound IDs like 
steam-usa<&>5
. Do not use the compound key — use only the value after 
<&>
.
bash
undefined
get-product-details
返回的结果中包含复合ID，如
steam-usa<&>5
。不要使用复合键——仅使用
<&>
后面的值。
bash
undefined

WRONG — compound key

错误示例 — 复合键

--cart_items '[{"product_id": "steam-usa", "package_id": "steam-usa<&>5"}]'
--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:

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

对于**命名型面额**，使用完整的精确字符串。常见错误：

```bash

WRONG — numeric guess for a named package

错误示例 — 对命名型套餐使用数值猜测

--cart_items '[{"product_id": "spotify-usa", "package_id": 1}]'
--cart_items '[{"product_id": "spotify-usa", "package_id": 1}]'

CORRECT

正确示例

--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]'
--cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]'

WRONG — partial match

错误示例 — 部分匹配

--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB"}]'
--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB"}]'

CORRECT

正确示例

--cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]'
--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"}]'
--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.
--cart_items '[{"product_id": "pubg-new-state-international", "package_id": "PUBG New State 300 NC"}]'

仅接受`get-product-details`返回的值。自定义金额（如`7`, `15`, `25`）会被拒绝。

"Search service is not available" (INTERNAL_ERROR)

"Search service is not available" (INTERNAL_ERROR)

Caused by invalid 
--country
values:
  • Lowercase country codes (
    us
    instead of 
    US
    ) — silently fails
  • 3-letter codes (
    USA
    instead of 
    US
    ) — fails
  • Full names (
    United States
    ) — fails
  • Nonexistent codes (
    ZZ
    ) — fails
  • Negative page (
    --page -1
    ) — fails
Fix: always use uppercase Alpha-2 ISO codes (
US
, 
IT
, 
BR
, 
GB
).
由无效的
--country
值导致：
  • 小写国家代码（如
    us
    而非
    US
    ）——静默失败
  • 三位代码（如
    USA
    而非
    US
    ）——失败
  • 完整国家名称（如
    United States
    ）——失败
  • 不存在的代码（如
    ZZ
    ）——失败
  • 负数页码（如
    --page -1
    ）——失败
解决方法：始终使用大写的两位ISO国家代码（如
US
, 
IT
, 
BR
, 
GB
）。

"Must be one of" errors

"Must be one of" 错误

The CLI validates enum values client-side before sending to the server.
OptionValid valuesCommon mistake
--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
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

Missing required options

缺少必填选项

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.
省略必填的
--cart_items
或
--product_id
会退出并提示：
error: required option '--<name> <value>' not specified
。CLI会在连接服务器前验证必填选项。

Cart exceeds 15 items

购物车商品超过15件

Maximum 15 items per 
buy-products
call. Server rejects with: 
Too big: expected array to have <=15 items
.
每次
buy-products
调用最多支持15件商品。服务器会拒绝并提示：
Too big: expected array to have <=15 items
。

per_page
exceeds 500

per_page
超过500

Server rejects: 
per_page must be less than 500
.
服务器会拒绝并提示：
per_page must be less than 500
。

Malformed JSON in 
--cart_items

--cart_items
中的JSON格式错误

Non-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.
非JSON字符串会导致崩溃并提示：
Unexpected token ... is not valid JSON
。确保值是有效的JSON。Shell引号很重要——对JSON使用单引号，内部使用双引号。

Missing 
package_id
in cart item

购物车商品缺少
package_id

Omitting 
package_id
from a cart item object results in: 
Invalid denomination 'undefined'
. Both 
product_id
and 
package_id
are required per item.
购物车商品对象中省略
package_id
会导致：
Invalid denomination 'undefined'
。每件商品都需要
product_id
和
package_id
。

Invoice / Product not found

发票/产品未找到

  • 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
.
  • 使用不存在的ID调用
    get-invoice-by-id
    ：
    Invoice not found
    （RESOURCE_NOT_FOUND）
  • 使用不存在的
    product_id
    调用
    buy-products
    ：
    Product '<slug>' is not available
    （RESOURCE_NOT_FOUND）
通过
search-products
验证产品别名，通过
list-invoices
验证发票ID。

Wrong 
MCP_URL

错误的
MCP_URL

Setting 
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
.
将
MCP_URL
设置为非Bitrefill端点会产生
StreamableHTTPError
，并返回远程服务器的HTML内容。取消设置该变量或指向
https://api.bitrefill.com/mcp
。

OAuth / auth failures

OAuth / 身份验证失败

If the CLI hangs or fails on startup:
  1. Run 
    bitrefill logout
    to clear stale credentials
  2. Re-run your command — a fresh OAuth flow will start
  3. Credentials file: 
    ~/.config/bitrefill-cli/api.bitrefill.com.json
如果CLI在启动时挂起或失败：
  1. 运行
    bitrefill logout
    清除过期凭证
  2. 重新运行命令——会启动新的OAuth流程
  3. 凭证文件路径：
    ~/.config/bitrefill-cli/api.bitrefill.com.json

Empty search results

搜索结果为空

found: 0
with no error typically means:
  • The 
    --category
    slug doesn't exist (no error, just empty results)
  • The product is not available in the specified 
    --country
  • --in_stock true
    (default) filters out products that are temporarily out of stock
Try broadening: remove 
--category
, change 
--country
, or set 
--in_stock false
.
found: 0
且无错误通常意味着：
  • --category
    别名不存在（无错误，仅返回空结果）
  • 产品在指定的
    --country
    不可用
  • --in_stock true
    （默认）过滤掉了暂时缺货的产品
尝试扩大搜索范围：移除
--category
，更改
--country
，或设置
--in_stock false
。

Unpaid invoices

未支付发票

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.
默认情况下
list-invoices
仅显示已支付发票。要查看所有发票（包括待支付/已过期）：使用
--only_paid false
。
发票过期时间为180分钟。如果未支付，需要创建新发票——无法重新支付已过期的发票。

Legal

法律条款