​

Bitrefill Plugin

[!IMPORTANT] Complete Base MCP onboarding first (SKILL.md). Path 1 (connect→JWT) is the default for agent-commerce. Fall back to Path 2 (pay-per-call x402) for multi-wallet or stateless agents. Use Path 3 (CLI) or Path 4 (Bitrefill MCP) only when the user has an existing Bitrefill account. Keep buy-products out of Bitrefill MCP autoApprove.

​

Overview

​

Detection

1. Base MCP sign + web_request + x402 payment tools available, agent can persist a JWT → Path 1.
2. Otherwise, or multi-wallet / no session persistence → Path 2.
3. Cannot run SIWX helpers (no shell/Node for checksum + message build) → Path 2 only; tell the user connect is unavailable.

4. Shell + npx @bitrefill/cli@latest --help → Path 3.
5. Bitrefill MCP tools exposed (search-products, buy-products, …) → Path 4.
6. Neither → install per Path 4 setup below; stop if both fail.

​

Path 4 setup (Bitrefill MCP)

• Cursor: .cursor/mcp.json or ~/.cursor/mcp.json:
  {
    "mcpServers": {
      "bitrefill": {
        "url": "https://api.bitrefill.com/mcp",
        "autoApprove": [
          "search-products", "get-product-details",
          "list-invoices", "get-invoice-by-id",
          "submit-prepayment-step", "update-order"
        ]
      }
    }
  }
  
  buy-products out of autoApprove.
• Claude Code: claude mcp add bitrefill --url https://api.bitrefill.com/mcp
• Reconnect/restart after install. MCP tools (verified): search-products, get-product-details, buy-products, submit-prepayment-step, list-invoices, get-invoice-by-id, update-order.

​

Auth and SIWX

​

EIP-55 checksum (required)

​

SIWX timing

​

Connect → JWT (Path 1)

1. web_request POST https://api.bitrefill.com/x402/connect with body {} and header Content-Type: application/json → 402 whose JSON body includes extensions["sign-in-with-x"].info (domain, uri, version, nonce, issuedAt, expirationTime, statement, resources) and supportedChains.
2. get_wallets → wallet address.
3. Pick Base: { chainId: "eip155:8453", type: "eip191" } from supportedChains.
4. Build EIP-4361 message with SIWX helpers below (toChecksumAddress → buildSiweMessage). The uri in the challenge for connect is https://api.bitrefill.com/x402/connect.
5. sign with type: "personal_sign", data: { message: <exact string> } → follow approval-mode.md → signature.
6. Build decomposed payload (not { message, signature }), base64-encode → sign-in-with-x request header (see payload shape below).
7. web_request POST https://api.bitrefill.com/x402/connect with body {}, Content-Type: application/json, and header sign-in-with-x: <base64> → 200 with { token, token_header: "X-Access-Token", expires_in } (default ~7200 s).
8. Store token in memory only. Attach X-Access-Token: <token> (raw JWT, no Bearer) on every subsequent gated web_request. Re-connect when expired.

​

SIWX for codes (after invoice/pay)

1. web_request GET https://api.bitrefill.com/x402/invoice/status?invoice_id=<uuid> → 402 with SIWX challenge (save the full JSON body).
2. Build message from challenge info — uri must match the challenged route (includes ?invoice_id=).
3. sign → follow approval-mode.md within 5 minutes.
4. web_request same URL with sign-in-with-x header → 200 with redemption_info.orders[].redemption_info (code, pin, extra_fields).
5. 403 → signing wallet is not the invoice payer. Sign with the wallet that paid.

​

Decomposed SIWX payload

{
  "domain": "api.bitrefill.com",
  "address": "0x<EIP-55 checksummed>",
  "statement": "<info.statement>",
  "uri": "<info.uri — must match the route being authenticated>",
  "version": "1",
  "chainId": "eip155:8453",
  "type": "eip191",
  "nonce": "<info.nonce>",
  "issuedAt": "<info.issuedAt>",
  "expirationTime": "<info.expirationTime>",
  "resources": ["<info.resources[]>"],
  "signature": "0x<full signature from get_request_status>"
}

​

SIWX message shape

<domain> wants you to sign in with your Ethereum account:
<checksummed_address>

<statement>

URI: <uri>
Version: 1
Chain ID: 8453
Nonce: <nonce>
Issued At: <issuedAt>
Expiration Time: <expirationTime>
Resources:
- <resource_url>

​

SIWX helpers (no external libraries)

const RC = [
  0x0000000000000001n,0x0000000000008082n,0x800000000000808an,0x8000000080008000n,
  0x000000000000808bn,0x0000000080000001n,0x8000000080008081n,0x8000000000008009n,
  0x000000000000008an,0x0000000000000088n,0x0000000080008009n,0x000000008000000an,
  0x000000008000808bn,0x800000000000008bn,0x8000000000008089n,0x8000000000008003n,
  0x8000000000008002n,0x8000000000000080n,0x000000000000800an,0x800000008000000an,
  0x8000000080008081n,0x8000000000008080n,0x0000000080000001n,0x8000000080008008n];
const ROT = [0,1,62,28,27,36,44,6,55,20,3,10,43,25,39,41,45,15,21,8,18,2,61,56,14];
const MASK = (1n<<64n)-1n;
const rotl = (x,n)=> n===0n ? x : ((x<<n)|(x>>(64n-n)))&MASK;
function keccakF(s){
  for(let round=0;round<24;round++){
    const C=new Array(5);
    for(let x=0;x<5;x++) C[x]=s[x]^s[x+5]^s[x+10]^s[x+15]^s[x+20];
    const D=new Array(5);
    for(let x=0;x<5;x++) D[x]=C[(x+4)%5]^rotl(C[(x+1)%5],1n);
    for(let x=0;x<5;x++) for(let y=0;y<5;y++) s[x+5*y]^=D[x];
    const B=new Array(25);
    for(let x=0;x<5;x++) for(let y=0;y<5;y++) B[y+5*((2*x+3*y)%5)]=rotl(s[x+5*y],BigInt(ROT[x+5*y]));
    for(let x=0;x<5;x++) for(let y=0;y<5;y++) s[x+5*y]=B[x+5*y]^(((~B[((x+1)%5)+5*y])&B[((x+2)%5)+5*y])&MASK);
    s[0]^=RC[round];
  }
}
function keccak256(bytes){
  const rate=136; const s=new Array(25).fill(0n);
  const padded=new Uint8Array(Math.ceil((bytes.length+1)/rate)*rate);
  padded.set(bytes); padded[bytes.length]^=0x01; padded[padded.length-1]^=0x80;
  for(let off=0;off<padded.length;off+=rate){
    for(let i=0;i<rate/8;i++){
      let lane=0n;
      for(let j=7;j>=0;j--) lane=(lane<<8n)|BigInt(padded[off+i*8+j]);
      s[i]^=lane;
    }
    keccakF(s);
  }
  const out=new Uint8Array(32);
  for(let i=0;i<4;i++){ let lane=s[i]; for(let j=0;j<8;j++){ out[i*8+j]=Number(lane&0xffn); lane>>=8n; } }
  return Buffer.from(out).toString('hex');
}
function toChecksumAddress(addr){
  const a=String(addr).toLowerCase().replace(/^0x/,'');
  const hash=keccak256(Buffer.from(a,'ascii'));
  let out='0x';
  for(let i=0;i<a.length;i++) out += parseInt(hash[i],16)>=8 ? a[i].toUpperCase() : a[i];
  return out;
}
function buildSiweMessage(info, address, chainIdCaip2){
  const chainNum = parseInt(/^eip155:(\d+)$/.exec(chainIdCaip2)[1], 10);
  let prefix = `${info.domain} wants you to sign in with your Ethereum account:\n${address}`;
  if (info.statement) prefix += '\n\n' + info.statement;
  const suffix = [
    `URI: ${info.uri}`, `Version: ${info.version}`, `Chain ID: ${chainNum}`,
    `Nonce: ${info.nonce}`, `Issued At: ${info.issuedAt}`,
  ];
  if (info.expirationTime) suffix.push(`Expiration Time: ${info.expirationTime}`);
  if (info.notBefore) suffix.push(`Not Before: ${info.notBefore}`);
  if (info.requestId) suffix.push(`Request ID: ${info.requestId}`);
  if (info.resources?.length) suffix.push(['Resources:', ...info.resources.map(r=>`- ${r}`)].join('\n'));
  return prefix + '\n\n' + suffix.join('\n');
}
function buildSiwxPayload(info, address, signature, chainIdCaip2){
  const payload = {
    domain: info.domain, address, statement: info.statement, uri: info.uri,
    version: info.version, chainId: chainIdCaip2, type: 'eip191',
    nonce: info.nonce, issuedAt: info.issuedAt, expirationTime: info.expirationTime,
    resources: info.resources, signature,
  };
  if (info.notBefore) payload.notBefore = info.notBefore;
  if (info.requestId) payload.requestId = info.requestId;
  return payload;
}
function encodeSiwxHeader(payload){
  return Buffer.from(JSON.stringify(payload)).toString('base64');
}

​

Business domain

​

Endpoints

​

Payment (Base USDC)

​

package_value (critical)

​

Request shapes

{ "items": [{ "product_id": "amazon_it-italy", "package_value": "10" }] }

{ "items": [{ "product_id": "iliad-italy", "package_value": "10", "refill_input": "+39XXXXXXXXXX" }] }

​

Surface routing

​

Claude show_widget

​

Orchestration

​

Path 1: Connect → browse → buy (default)

1. Connect — SIWX flow above → store JWT and expires_in. Do this once per session.
2. Confirm funds — when needed, check USDC on Base before pay.
3. Search — web_request GET /x402/gift-cards/search?q=<term>&country=<ISO> with X-Access-Token. Take slug from products[]. (Or esims/search, topups/search.)
4. Detail — web_request GET /x402/products/detail?slug=<slug> + token. Confirm in_stock, currency, packages[], recipient_required.
5. Create — web_request POST /x402/invoice/create + token with { "items": [{ "product_id": "<slug>", "package_value": "<exact>" }] } (+ refill_input if top-up). Read invoice_id, price_usd.
6. Confirm with user — show exact USDC total, product, denomination. Get explicit approval to pay.
7. Pay — x402 on POST https://api.bitrefill.com/x402/invoice/pay with { invoice_id }, maxPayment just above price_usd → approval-mode.md → complete x402 request.
8. Poll — web_request GET /x402/invoice/status?invoice_id=<id> + token until delivery_status is all_delivered.
9. Codes — if redemption_info missing, run SIWX for codes with the paying wallet. Deliver code / pin securely (Risks & Warnings).

​

Path 2: Pay-per-call x402

1. Confirm USDC on Base when needed.
2. For each gated step: web_request → 402 → x402 pay that URL/method/body, maxPayment: "0.01" → approval-mode.md.
3. Follow next_step through detail → create → pay.
4. Invoice pay: maxPayment just above price_usd.
5. Poll status; SIWX for codes from paying wallet.

​

Path 3: CLI

npx @bitrefill/cli@latest --help
npx @bitrefill/cli@latest --json whoami
npx @bitrefill/cli@latest search-products --query "Steam" --country US
npx @bitrefill/cli@latest buy-products \
  --cart_items '[{"product_id":"steam-usa","package_id":5}]' \
  --payment_method usdc_base --return_payment_link true

1. x402 — pay x402_payment_url via Base MCP x402 tools → approval-mode.md.
2. Direct send — send to payment_info address/amount on base → approval-mode.md → poll CLI/get-invoice-by-id until paid.

​

Path 4: MCP

​

Submission

​

Example prompts

​

Risks & Warnings

• pii — Redemption codes, eSIM QR URLs, PINs are bearer credentials. Never log, commit, or paste in public channels. Return codes only when the user explicitly asks.
• irreversible — Digital goods are non-refundable once fulfilled. Confirm product, denomination, price, and payment before pay.
• Invoice expiry — ~15 min price lock. Stale pay URL → create a new invoice.
• Connect token — X-Access-Token is a bearer secret (~2 h). Never echo in chat. Re-connect when expired.
• EIP-55 checksum — mandatory for every SIWX flow; use helpers above.
• CLI session — ~/.config/bitrefill-cli/<host>.v1.json is sensitive.

​

Notes

• Country codes: Alpha-2 uppercase (US, IT).
• X-Access-Token header only — Base MCP strips Authorization.
• Fee schedule: search $0.002 · detail/checkout$0.001 · create $0.002 · status$0.001.
• Connect JWT TTL: default 120 minutes.
• HTTP 500 on invoice/create — wrong package_value; retry without paying until onchain history confirms no charge.
• 402 after SIWX send — stale nonce, wrong checksum, or malformed payload; re-fetch challenge and re-sign within 5 minutes.
• 403 on SIWX route — wrong wallet; sign with the invoice payer.
• INVOICE_NOT_PAYABLE on pay — already settled; poll status instead.
• Docs: github.com/bitrefill/agents, docs.bitrefill.com