mcpField
B
bitrefill-cli

bitrefill-cli

github.com/bitrefill其他2876 次安装1 周前更新
代码仓库

关于 bitrefill-cli

通过 Bitrefill 查找和购买礼品卡、手机充值及 eSIM 的命令行技能。它指导 Agent 查询商品详情、付款和跟踪订单，并提供真实货币交易的安全措施。

主要功能

  1. 01按关键词和国家搜索商品
  2. 02查看商品及面额详情
  3. 03使用支持的支付方式购买
  4. 04跟踪发票和订单
  5. 05付款前确认购买

适用场景

  1. 01查找指定国家的礼品卡
  2. 02购买 eSIM 或手机充值
  3. 03付款后查询发票
  4. 04落实购买审批和兑换码保护

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bitrefill/agents --skill bitrefill-cli

安装后在 Claude Code 中输入/bitrefill-cli确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
commands.md
payment.md
troubleshooting.md

详细介绍

Bitrefill CLI

通过 Bitrefill CLI 搜索、购买并交付数字商品（礼品卡、手机充值、eSIM）。

要求

  • 使用此技能需要 Bitrefill 账户。通过 Bitrefill API 密钥或 OAuth 进行身份验证。详情请参阅设置。
  • 需要 加密钱包 来发送加密货币或向 x402 端点（Base 上的 USDC）付款。本技能不提供此功能。
  • 建议使用“浏览器使用”MCP 或 CLI，以便 Agent 在品牌网站上兑换代码，实现完全自主的购物体验。本技能不提供此功能。

支持的支付方式

即时 Agent 支付的最佳支付体验是通过 balance 使用商店余额，其次是 Base 上通过 x402 的 USDC，然后是 Lightning。所有其他加密货币支付都要求 Agent 轮询发票状态以确认付款。

CLI 通过 bitrefill buy-products --help 返回完整列表

  • balance — 即时履约，无需等待链上确认。用户在 bitrefill.com 预充值。自然形成消费上限。
  • usdc_base 配合 x402 — 使用 --return_payment_link true（默认）获取 x402_payment_url。支持 x402 的 Agent 通过 Base 自主完成支付。
  • 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
  • usdt_polygon — Polygon（137），USDT
  • usdt_erc20 — Ethereum（1），USDT
  • 支付卡、本地支付方式及其他加密货币支付方式可在 --return_payment_link true 选项返回的结账页面中找到。

消费保障

此技能支持 真实货币交易。付款确认后，购买将立即履约。

  • 默认：购买前始终确认。 展示产品、面额、价格和支付方式；等待明确批准后再执行 buy-products。仅在用户明确选择当前会话自主购买时才自动购买。
  • 数字商品一旦交付，仅在其无法正常使用时才可退款。根据 欧盟消费者权益，礼品卡代码等数字商品不适用 14 天无理由退货政策。
  • 礼品卡代码可被视为类似现金，因此应安全存储，不得公开分享。只有 Agent 的所有者才有权访问该代码。优先使用加密数据存储而非纯文本存储代码。
  • 尽可能避免重复写入数字代码。如有可能，优先使用 内存存储，直到代码被兑换，且仅在此时以编程方式访问和使用它。
  • 如果用户索要代码，请返回代码，但建议他们 安全存储、不要公开分享，并尽快使用。
  • 使用 专用且余额有限的账户 — 切勿让 Agent 访问高余额账户。
  • 服务条款： https://www.bitrefill.com/terms/ 包含有关退款政策和购买限制的重要信息。
  • 记录每次购买： invoice_id、产品、金额、支付方式。
  • 不是钱包： 此技能不是钱包。它是在 Bitrefill 上购买产品的工具。它不负责存储私钥或管理您的加密钱包。
  • 浏览器使用： 当尝试在品牌网站上兑换代码时，反机器人保护机制可能会阻止 Agent。在这种情况下，询问用户是否希望手动完成兑换流程，并在需要时将代码返回给用户。

设置

安装
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 key：

export BITREFILL_API_KEY=YOUR_API_KEY

替代方案：不带 API key 运行任意命令，以触发基于浏览器的 OAuth。Token 存储在 ~/.config/bitrefill-cli/api.bitrefill.com.json。使用 bitrefill logout 清除。

环境变量
变量用途
BITREFILL_API_KEY无头认证（跳过 OAuth）

核心工作流

search-products → get-product-details → buy-products → get-invoice-by-id / list-orders
1. 搜索
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. 获取详情
bitrefill get-product-details --product_id "steam-usa"

返回一个 packages 数组。每个条目都有一个 package_value —— 将其用作 buy-products 中的 package_id。

忽略复合键，例如 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 数组 [...]，即使只有一个条目也是如此。

# 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

响应包含 invoice_id、payment_link 和 x402_payment_url。

每次调用最多 15 个条目。

4. 追踪
bitrefill get-invoice-by-id --invoice_id "UUID"
bitrefill list-orders --include_redemption_info true

关键陷阱

cart_items 必须是数组，而不是对象：

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

使用 <&> 之后的 package_value，而不是复合键：

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

命名/时长类型的 package_id 必须精确且区分大小写：

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

国家/地区代码必须为大写 Alpha-2：

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

参考

按需加载：

参考何时使用
commands任意命令的完整选项表
payment支付方式列表、x402 协议、响应字段
troubleshooting上述关键陷阱之外的错误

评论

支持 Markdown