🇺🇸English

Bitrefill CLI — Real-World Spending for Agents

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

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.

Required Credentials & Configuration

Provisioning Credentials for Autonomous Agents

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.

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.
• Preferbalance 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.

Prerequisites

The CLI must be installed and authenticated before use.

Installation

From NPM (recommended)

npm install -g @bitrefill/cli

From Source

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

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/.

# 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.

Environment

Recommended Payment for Agents

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.

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

Available Commands

Commands are discovered dynamically from the MCP server. Run bitrefill --help for the current list.

search-products

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

get-product-details

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

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:

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.

buy-products

--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

Response fields (whenreturn_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

list-invoices

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"

get-invoice-by-id

bitrefill get-invoice-by-id --invoice_id "27713c64-6715-48d8-95ef-45eed23efef7"

list-orders

bitrefill list-orders
bitrefill list-orders --limit 5 --include_redemption_info true

get-order-by-id

bitrefill get-order-by-id --order_id "69af584e8a2639d14ac35e96"

Returns redemption code or link if the order is unsealed (paid and delivered).

logout

bitrefill logout

Deletes stored OAuth credentials from ~/.config/bitrefill-cli/.

Payment

Payment Methods

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), raw .

x402 Protocol

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.

Troubleshooting

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}]'

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 <&>.

# 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.

"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).

"Must be one of" errors

The CLI validates enum values client-side before sending to the server.

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 exceeds 15 items

Maximum 15 items per buy-products call. Server rejects with: Too big: expected array to have <=15 items.

per_page exceeds 500

Server rejects: per_page must be less than 500.

Malformed JSON in --cart_items

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.

Missing package_id in cart item

Omitting package_id from a cart item object results in: Invalid denomination 'undefined'. Both product_id and package_id are required per item.

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.

Wrong 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.

OAuth / auth failures

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

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.

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.

Legal

• Terms of Service
• Privacy Policy

Weekly Installs

0

Repository

bitrefill/agents

GitHub Stars

2

First Seen

Jan 1, 1970

Security Audits

SocketFail