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. Connect with your Bitrefill account via OAuth, then ask your AI to find and buy gift cards, eSIMs, mobile refills, or bill-payment products directly.

What You Can Do

With Bitrefill MCP, your AI assistant can:

• Search for gift cards, prepaid payment cards, eSIMs, and refills across 170+ countries
• Get product details including available denominations, pricing, and recipient requirements
• Purchase products using crypto or your Bitrefill account balance
• Send purchases as gifts via email
• Complete multi-step bill-payment forms (prepaid cards, utility bills, and more)
• Track invoices and retrieve redemption codes
• Update gift card balance tracking and archive delivered orders

Connecting to MCP

Every MCP session is authenticated. When you connect, you sign in to your Bitrefill account via OAuth — this is the default path for all supported clients.

https://api.bitrefill.com/mcp

When you first connect, your client redirects you to Bitrefill to sign in and authorize access. Once connected, all 7 tools are available.

For programmatic access or clients that don't support OAuth, use an API key in the URL instead:

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

Get your API key at bitrefill.com/account/developers. See Setup Guides for client-specific instructions.

Affiliate attribution

Add ?ref=[AFFILIATE_CODE] to your MCP URL to attribute all purchases from that connection to your affiliate account:

https://api.bitrefill.com/mcp?ref=YOUR_AFFILIATE_CODE

Users who connect through this URL still sign in with their own Bitrefill account via OAuth — the affiliate code only attributes their purchases to you, it does not replace account sign-in.

To become an affiliate partner, apply at bitrefill.com/integrate.

Available Tools

The MCP server exposes 7 tools:

Most tools return responses in TOON format. buy-products returns JSON with an agent_instructions field that guides the agent on next steps.

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 get-product-details to get available denominations.

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

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

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

Returns product info including packages — an array of available denominations. Each package has:

• package_id — Full ID in the format {product_id}<&>{value} (e.g., amazon_com-usa<&>50)
• package_value — The denomination value alone (e.g., "50") — use this as package_id in buy-products

If the product has a range field, custom denominations are supported within range.min–range.max (multiples of range.step). Pass any valid value as package_id in buy-products.

Check recipient_type to see if a phone number, account ID, email, or username is required for refills and top-ups.

Step 2: Bill Payment Prepayment (If Required)

Some products (prepaid Visa, utility bills, etc.) include a prepayment block in the get-product-details response. Before purchasing, the agent must complete the prepayment form chain:

submit-prepayment-step(
  product_id="prepaid-visa-usa",
  step_number=1,
  form_data={ "first_name": "Alice", "last_name": "Smith" }
)

Repeat with each returned form until the response has step="final". Pass the returned bill_payment_id to buy-products.

Step 3: Create an Invoice

The agent uses buy-products with a JSON array of cart items:

buy-products(
  cart_items=[
    { "product_id": "amazon_com-usa", "package_id": "50" }
  ],
  payment_method="bitcoin",
  return_payment_link=true
)

Cart item fields:

Parameters:

• cart_items — JSON array of 1–15 items (see table above)
• payment_method — See Payment Methods
• balance_currency — Optional. Sub-account to debit when using balance: EUR, USD, or XBT
• 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
• x402_payment_url — Alternative payment endpoint for x402-capable wallets
• payment_info — Crypto address and amount (for wallet payments)
• expiration_minutes — Time until invoice expires
• esim_install_links — Install links for eSIM orders
• agent_instructions — Next steps for the agent (poll status, payment options)

You cannot change the payment method after creating an invoice. To use a different method, call buy-products again.

Step 4: Complete Payment

Three options:

Option A: Web checkout
The agent provides the payment_link for you to complete payment in your browser.

Option B: x402 wallet
A connected wallet agent can pay via the x402_payment_url.

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

Balance payments (payment_method="balance") confirm automatically — no manual payment step needed.

Step 5: Check Payment Status

The agent polls get-invoice-by-id to check if payment was received. Orders are always included in the response.

get-invoice-by-id(invoice_id="6654a2ea-0df7-4f44-bc72-c1c6ad8b7b34")

Invoice statuses:

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

Step 6: Get Redemption Info

Once the invoice status is complete, read redemption info from the nested orders array in the get-invoice-by-id response:

• orders[].redemption_info — Gift card code or redemption link (when redemption_available is true)
• orders[].esim_install_link — eSIM install link for eSIM orders

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

Gift Purchases

Include a gift object on any cart item to send the purchase as a gift email:

buy-products(
  cart_items=[
    {
      "product_id": "amazon_com-usa",
      "package_id": "50",
      "gift": {
        "recipient_name": "Jane",
        "recipient_email": "[email protected]",
        "sender_name": "John",
        "message": "Happy birthday!",
        "send_date": "2026-06-01T12:00:00Z",
        "theme": "birthday"
      }
    }
  ],
  payment_method="balance"
)

Gift themes: red, green, yellow, birthday, christmas, bitcoin, chinese, valentines

If send_date is omitted, the gift is sent immediately upon delivery.

Order Management

Use update-order to track gift card usage or manage order visibility. Requires a delivered order.

update-order(order_id="507f1f77bcf86cd799439011", remaining_amount=25.00)

Parameters:

• order_id — 24-character hex MongoDB ID from the orders array in invoice responses — not the invoice UUID
• remaining_amount — Set the remaining gift card balance (replaces spent history)
• is_archived — Archive or unarchive the order

At least one of remaining_amount or is_archived is required.

Use list-invoices to browse your invoice history. It returns invoices with status payment_detected, payment_confirmed, or complete — unpaid invoices are not included.

Supported Clients

Payment Methods

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

Crypto:

• bitcoin, litecoin, lightning, ethereum, solana
• usdc_polygon, usdt_polygon, usdc_erc20, usdt_erc20, usdt_trc20
• usdc_arbitrum, usdc_solana, usdc_base, eth_base

Account balance:

• balance — Pays from your Bitrefill account. Optionally set balance_currency to EUR, USD, or XBT to choose which sub-account to debit.
• cashback — Pays from your BTC cashback/rewards balance.