bitrefill-cli

Bitrefill CLI

Bitrefill CLI を使って、デジタル商品（ギフトカード、モバイルチャージ、eSIM）を検索、購入、配達できます。

要件

• このスキルを使用するには、Bitrefill アカウントが必要です。認証には Bitrefill API キーまたは OAuth を使用します。詳しくはセットアップをご覧ください。
• 暗号資産を送金する、または x402 エンドポイント（Base 上の USDC）で支払うには、暗号資産ウォレットが必要です。このスキルには含まれていません。
• エージェントがブランドのウェブサイトでコードを引き換えることで、完全に自律的な購入体験を実現するには、「Browser usage」MCP または CLI の使用を推奨します。このスキルには含まれていません。

対応する支払い方法

エージェントによる即時決済には、balance によるストアクレジット、次に x402 経由の Base 上の USDC、続いて Lightning が最適です。それ以外の暗号資産による支払いでは、支払いを確認するため、エージェントが請求書のステータスをポーリングする必要があります。

CLI は全件の一覧を bitrefill buy-products --help で表示します。

• balance — 即時に履行され、オンチェーンでの待ち時間はありません。ユーザーは bitrefill.com で事前に入金します。自然な支出上限になります。
• usdc_base（x402 経由） — --return_payment_link true（デフォルト）を指定すると、x402_payment_url を取得できます。x402 対応エージェントが 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 の実行前に明示的な承認を待ちます。自律的な購入は、ユーザーが現在のセッションで明示的に許可した場合に限ります。
• デジタル商品は配達後、期待どおりに動作しない場合に限り返金対象となります。EU 消費者権利に基づき、ギフトカードコードなどのデジタル商品には、14 日間のクーリングオフ制度は適用されません。
• ギフトカードコードは現金同様に扱われる場合があるため、安全に保管し、公開しないでください。コードにアクセスできるのはエージェントの所有者だけにしてください。コードはプレーンテキストではなく、暗号化されたデータストレージに保存することを推奨します。
• デジタルコードの再出力は、できる限り避けてください。可能であれば、コードを引き換えるまでメモリ内に保存し、その後にプログラムからアクセスして使用することを推奨します。
• ユーザーからコードを求められた場合は返却してください。その際、安全に保管し、公開せず、できるだけ早く使用するよう伝えてください。
• 専用の低残高アカウントを使用してください。残高の多いアカウントへのアクセスをエージェントに決して許可しないでください。
• 利用規約： https://www.bitrefill.com/terms/ には、返金ポリシーと購入上限に関する重要な情報が記載されています。
• 購入をすべて記録してください： invoice_id、商品、金額、支払い方法。
• ウォレットではありません： このスキルはウォレットではなく、Bitrefill で商品を購入するためのツールです。秘密鍵の保管や暗号資産ウォレットの管理は行いません。
• ブラウザーの使用： ブランドのウェブサイトでコードを引き換えようとすると、ボット対策機能によってエージェントがブロックされることがあります。その場合は、ユーザーに手動で引き換え手続きを完了するか尋ね、希望する場合はコードをユーザーに返してください。

セットアップ

インストール

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キーを生成します。

export BITREFILL_API_KEY=YOUR_API_KEY

別の方法として、APIキーなしで任意のコマンドを実行すると、ブラウザー経由のOAuth認証が開始されます。トークンは~/.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には大文字のISO Alpha-2コード（US、IT、BR）を指定する必要があります。--product_typeにはgiftcardまたはesim（単数形）を指定します。

カテゴリーの検索： --query "*"を指定して検索すると、スラッグと件数を含むcategories配列がレスポンスに含まれます（例：food、games、streaming）。特定の国で利用可能なカテゴリーを確認するには、--countryを追加します。これらのスラッグを--categoryの値として使用してください。

2. 詳細を取得

bitrefill get-product-details --product_id "steam-usa"

packages配列が返されます。各エントリーにはpackage_valueが含まれます。これをbuy-productsのpackage_idとして使用してください。

steam-usa<&>5のような複合キーは無視してください。<&>の後の値だけを使用します。

額面の種類は3つあります。

• 数値： 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が含まれます。

1回の呼び出しで指定できる商品は最大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

リファレンス

必要に応じて読み込んでください。

リファレンス	使用する場面
コマンド	各コマンドのオプション一覧を確認する場合
支払い	支払い方法の一覧、x402プロトコル、レスポンスフィールドを確認する場合
トラブルシューティング	上記の特に注意する点以外のエラーが発生した場合