| name | bitrefill |
| description | Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, eSIMs, 180+ countries. Capability routing: probe harness (exec, egress, MCP), pick touchpoint (Bitrefill MCP, x402 REST via Base MCP, CLI, API, browse), wallet (balance, x402, send). Favors autonomous purchase, minimal HITL. Triggers: Bitrefill, gift cards, mobile top-up, eSIM, crypto, Lightning, USDC, x402. |
| compatibility | Routes by harness × touchpoint × wallet. Touchpoints: Bitrefill MCP (OAuth), x402 REST (Base MCP web_request → api.bitrefill.com), CLI ≥0.3.0, v2 REST, residential browse. Wallets: Bitrefill balance, Base MCP, AgentCash, CDP awal, Phantom/MetaMask sign-only. OpenClaw + Claude Chat: dedicated harness guides. |
| metadata | {"author":"bitrefill","version":"3.2.0","homepage":"https://www.bitrefill.com","docs":"https://docs.bitrefill.com","repository":"https://github.com/bitrefill/agents"} |
Bitrefill
Digital goods (gift cards, mobile top-ups, eSIMs) — 180+ countries, 1,500+ brands. Pay: crypto, Lightning, USDC x402, pre-funded balance.
Routes by harness × wallet × touchpoint — detect each layer, read its guide, then pick the lowest-HITL stack that fits the case.
User-facing language
Concierge voice — crypto should feel like buying a gift card, not wiring a wallet. Applies to every visible surface: assistant messages, thinking summaries, tool-call titles. Match the user's language throughout — localize all copy; never paste English templates verbatim into Italian (or other) sessions.
Say: "I'll search for that gift card" · "Sign in with your Base wallet once" · "Approve the payment in your Base Account" · "Your code is ready."
Never say: Path 1/2, Step 1/2/3, harness, touchpoint, x402, MCP, SIWX, JWT, connector, endpoint, script, invoice, flusso ottimale, micro-fee, guest checkout, account not connected — or name internal tools/routes.
| Internal | Say instead |
|---|
| connect / SIWX / JWT | "Sign in with your Base wallet once" (free — just to browse) |
| search / detail | "Searching for [product]…" |
| invoice/create | "[Product] — [amount]: [total] USDC. Confirm?" |
| invoice/pay / x402 pay | "Approve the payment in your Base Account" |
| poll / delivery | "Your code is ready." |
Flow: ≤4 user-visible messages — (1) goal + first approval if needed, (2) price receipt + confirm, (3) payment approval, (4) delivery. Between user gates: tool calls only — no status chatter unless blocked/error. Decide routing in silence; open with the goal, not the process; say each fact once; poll silently (never ask user to ping you).
Receipt (one message): product · face value · exact USDC total (network) · balance · validity · FX in one clause if needed. Delivery: code + non-refundable once, neutrally.
Reference doc banner (copy verbatim to top of each guide): Internal mechanics — never voiced. Speak / think / title tools in plain shopping language: "sign in with your wallet", "approve the payment", "your code is ready"; never x402 / SIWX / JWT / path / endpoint.
When Bitrefill sign-in is missing but Base wallet works: one wallet sign-in, then browse and one payment approval — not a separate fee for every search. Host-specific copy → claude-chat.md § User voice.
How to route
Safeguards → safeguards.md. Then three phases — read the guide for each layer before acting:
1. Detect harness → read harness instructions
Probe what host you are on (exec/shell, egress, MCP connectors, browser, generative UI). Match to a profile and open that harness doc — it overrides generic defaults.
Harness doc tells you what is off limits (no CLI on Claude Chat, no sandbox curl, etc.) and any host-specific ranked stack.
2. Detect wallets → read wallet instructions
Probe payment capabilities available in this session (independent of catalog channel):
Full probe list → decision-engine.md § Phase 2.
3. Pick touchpoint × wallet for this case
Cross harness limits, wallet availability, and intent (browse vs buy; Bitrefill account vs guest USDC). Choose the stack with the lowest residual HITL that still works — then read the touchpoint doc and execute.
Touchpoint (catalog/checkout channel — first viable match):
| If | Read |
|---|
search-products / buy-products visible (OAuth or API key) | mcp.md |
Base MCP web_request + guest USDC, no Bitrefill account | x402.md — wallet sign-in (Path 1), not pay-per-call |
| Shell + npm, no Bitrefill MCP | cli.md |
| Direct HTTP only | api.md |
| Browse-only + residential browser | browse.md |
| None viable | Send user bitrefill.com link |
Wallet at pay time — pick best available for the chosen touchpoint → payment.md, matrix.md. Typical pairings:
| Touchpoint | Prefer wallet |
|---|
| Bitrefill MCP | balance + auto_pay → Base MCP pay → payment link |
| Guest checkout (x402 REST) | AgentCash / awal → Base MCP sign-in + pay → never pay-per-call browse when sign-in works |
| CLI | Same wallet rank as above at buy-products time |
Conflict resolution + global rank → decision-engine.md § Phase 3.
Top spending safeguards
Real-money transactions. Codes instant; digital goods non-refundable once fulfilled.
- Confirm before buy unless user opted autonomous purchasing this session.
- Codes = cash — never paste public channels; prefer in-memory.
- Dedicated low-balance account — never give agent wallet seeds. Skill not a wallet.
- Log every purchase —
invoice_id, product, amount, payment method.
Full safeguards + per-host hardening → safeguards.md.
References
Harnesses
Touchpoints
Wallets
Cross-cutting
Source of truth
Skill summarizes + routes. Exhaustive enums → https://docs.bitrefill.com.
