eCommerce MCP Server

The Bitrefill eCommerce MCP Server lets AI assistants like ChatGPT, Claude, and Cursor search for products, check details, and make purchases on your behalf. Instead of switching between apps, you can ask your AI to find and buy gift cards or eSIMs directly.

What You Can Do

With Bitrefill MCP, your AI assistant can:

• Search for gift cards and eSIMs across 170+ countries
• Get product details including available denominations and pricing
• Purchase products using crypto (Bitcoin, Lightning, Ethereum, USDC, USDT, Solana) or account balance
• Track your invoices and orders

Available Tools

The MCP server exposes 7 tools:

How a Purchase Works

To complete a purchase, the agent follows this flow:

Step 1: Search and Select a Product

The agent uses search-products to find products, then product-details to get available denominations.

search-products(query="Amazon", country="US")

Returns a list of matching products with their IDs (slugs).

product-details(product_id="amazon_com-usa", currency="USD")

Returns product info including packages — an array of available denominations. Each package has a package_id in the format {product_id}<&>{value} (e.g., amazon_com-usa<&>50).

Step 2: Create an Invoice

The agent uses buy-products with the selected package IDs to create an invoice.

buy-products(
  cart_items="amazon_com-usa<&>50",
  payment_method="bitcoin",
  return_payment_link=true
)

Parameters:

• cart_items — Pipe-separated list of package IDs (e.g., amazon_com-usa<&>50|spotify-usa<&>30)
• payment_method — One of: bitcoin, lightning, ethereum, usdc_polygon, usdt_polygon, usdc_erc20, usdt_erc20, usdc_arbitrum, usdc_solana, usdc_base, eth_base, balance
• return_payment_link — If true, returns a web checkout link. If false, returns crypto payment details (address, amount).

Returns:

• invoice_id — Use this to check payment status
• payment_link — Web URL to complete payment manually
• payment_info — Crypto address and amount (for wallet payments)
• expiration_minutes — Time until invoice expires

Step 3: Complete Payment

Two options:

Option A: Manual payment via link The agent provides the payment_link for you to complete payment in your browser.

Option B: Wallet payment If return_payment_link=false, the agent gets the crypto payment_info.address and amount. A connected wallet agent can send payment directly.

Step 4: Check Payment Status

The agent polls get-invoice-by-id to check if payment was received.

get-invoice-by-id(invoice_id="...", include_orders=true)

Invoice statuses:

• unpaid — Waiting for payment
• payment_detected — Payment seen, waiting for confirmation
• payment_confirmed — Payment confirmed
• complete — Order delivered

Step 5: Get the Gift Card Code

Once the invoice status is complete, the agent retrieves the redemption info.

get-order-by-id(order_id="...", include_redemption_info=true)

Returns redemption_info containing the gift card code or redemption link.

For eSIMs, the response includes esim_install_link to install the eSIM on your device.

The full purchase flow typically happens in a single conversation. The agent handles all the steps — you just confirm the purchase and payment.

Authentication Options

There are two ways to connect to the Bitrefill MCP server:

OAuth (Recommended)

Use this URL with any client that supports OAuth:

https://api.bitrefill.com/mcp

When you first connect, you'll be redirected to Bitrefill to sign in and authorize access. The client handles the OAuth flow automatically — no API key needed.

Best for: Interactive use with ChatGPT, Claude Desktop, Claude Code, and Cursor.

API Key

Generate an API key and append it to the URL:

https://api.bitrefill.com/mcp/YOUR_API_KEY

Get your API key at bitrefill.com/account/developers.

Best for: Programmatic access, automation, or clients that don't support OAuth.

Supported Clients

Payment Methods

When purchasing through the MCP server, you can pay with:

• Crypto: Bitcoin, Lightning Network, Ethereum, USDC, USDT, Solana
• Account Balance: Use funds already in your Bitrefill account