@bitrefill/cli

Browse, buy, and manage gift cards, mobile top-ups, and eSIMs from the command line.

The CLI connects to the Bitrefill MCP server and dynamically discovers available tools, exposing each as a subcommand with typed options.

Install

npm install -g @bitrefill/cli

Quick start (init)

Non-interactive and agent-driven usage:

# Initialize in non-interactive mode
bitrefill init

# Force OpenClaw integration even if not auto-detected
bitrefill init --openclaw

bitrefill login --email [email protected]
bitrefill verify --code 123456

OpenClaw + Telegram

If you use OpenClaw as your AI agent gateway (e.g. via Telegram), bitrefill init does extra work:

• Adds an MCP server entry to ~/.openclaw/openclaw.json
• Generates ~/.openclaw/skills/bitrefill/SKILL.md so the agent knows about all available tools

After init, tell your Telegram bot: "Search for Netflix gift cards on Bitrefill".

Authentication

Sign in

Two steps. Use the emailed verification --code; add --otp if your account also requires a second factor (for example TOTP).

bitrefill login --email [email protected]
bitrefill verify --code 123456

Non-interactive / CI

In environments without a TTY (e.g. CI, Docker, scripts), ensure credentials are provided by your runtime and then run bitrefill init.

Usage

bitrefill [--json] [--no-interactive] <command> [options]

Human-readable output (default)

Tool results are pretty-printed JSON on stdout. Status messages (OAuth prompts, etc.) also go to stdout.

Machine-readable output (--json)

Pass --json anywhere before the subcommand so scripts and jq get a single JSON value per invocation on stdout:

• stdout: Only the tool result (JSON). Text payloads from the server may be JSON or TOON; the CLI decodes TOON to JSON when needed.
• stderr: Progress messages, errors, and client errors (JSON { "error": "..." } for failures).

Example:

bitrefill --json search-products --query "Amazon" --per_page 1 | jq '.products[0].name'

LLM context (llm-context)

Generates Markdown from the MCP tools/list response: tool names, descriptions, parameter tables, JSON Schema, example bitrefill … invocations, and example MCP tools/call payloads. Intended for CLAUDE.md, Cursor rules, or .github/copilot-instructions.md.

• stdout by default, or -o / --output <file> to write a file.
• Uses the same auth as other commands.
• The generated Connection line shows a redacted MCP URL, not sensitive credentials.

bitrefill llm-context -o BITREFILL-MCP.md
# or: bitrefill llm-context > BITREFILL-MCP.md

Examples

# First-time setup
bitrefill init

# Search for products
bitrefill search-products --query "Netflix"

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

# Buy a product
bitrefill buy-products --cart_items '{"product_id": "steam-usa", "package_id": 10}' --payment_method usdc_base

# List your orders
bitrefill list-orders

# List available commands
bitrefill --help

# Clear local login session
bitrefill logout

# Export tool docs for coding agents (see "LLM context" above)
bitrefill llm-context -o BITREFILL-MCP.md

Development

From the repository root (requires pnpm):

pnpm install
pnpm format    # Prettier check
pnpm test      # Vitest unit tests
pnpm build     # Compile to dist/
pnpm dev -- --help   # Run CLI via tsx without building

Publishing to npm is triggered by GitHub Releases; see .github/RELEASING.md.

Paying

Flow: get-product-details → pick product_id + package_id → buy-products with --cart_items and --payment_method.

Payment methods

| Method | Chain / asset | Response fields (raw) | |--------|----------------|----------------------| | bitcoin | Bitcoin (SegWit) | address, BIP21, lightningInvoice, satoshiPrice | | lightning | Lightning | lightningInvoice, satoshiPrice | | ethereum | Ethereum mainnet, native ETH | address, paymentUri / BIP21, altcoinPrice (ETH) | | eth_base | Base, native ETH | address, paymentUri (@8453) | | usdc_base | Base (8453) | address, paymentUri, contractAddress (USDC) | | usdc_arbitrum | Arbitrum (42161) | address, paymentUri, contractAddress | | usdc_polygon | Polygon (137) | address, paymentUri, contractAddress | | usdc_erc20 | Ethereum (1) | address, paymentUri, contractAddress | | usdc_solana | Solana | address (base58), contractAddress (USDC SPL) | | usdt_polygon, usdt_erc20 | Same as USDC, USDT | Same shape | | balance | Bitrefill account credit | No address; invoice created and paid from balance |

Response mode

• --return_payment_link false: response includes address, amount, BIP21 / paymentUri (and for Bitcoin, also lightningInvoice). Use for wallet pay.
• --return_payment_link true (default): response includes payment_link (browser checkout) and x402_payment_url for programmatic pay.

x402

x402 = HTTP 402 + payment-required header (Base64 JSON: amount, payTo, accepted networks, timeout). GET x402_payment_url → 402 + instructions → send crypto → resubmit with payment proof. For agents/tools; humans use payment_link.

Check status: get-invoice-by-id --invoice_id <id>.

Legal

• Terms of Service
• Privacy Policy