About bitrefill
bitrefill is an agent skill for routing purchases of Bitrefill digital goods through the available host, wallet, and checkout options. It guides capability detection, user-facing language, purchase confirmation, and safeguards for payments and code delivery.
Key features
- 01Detect host and wallet capabilities
- 02Choose a checkout route
- 03Localize customer-facing messages
- 04Require purchase confirmation
- 05Protect codes and log purchases
Use cases
- 01Find a viable purchase route for a session
- 02Guide a wallet sign-in and payment
- 03Present a purchase receipt and deliver a code
MCP support
The skill routes to Bitrefill MCP when its search-products or buy-products tools are available. It also documents other touchpoints, including x402 REST, CLI, and direct API.
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/bitrefillin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
references/safeguards.mdtroubleshooting.mdreferences/harnesses/capability-matrix.mdclaude-chat.mddecision-engine.mdgrok-bot.mdopenclaw.mdreferences/touchpoints/api.mdbrowse.mdcli-headless-auth.mdcli.mdmcp.mdx402.mdreferences/wallets/agentcash.mdbase-mcp.mdcdp-awal.mdmatrix.mdmetamask.mdpayment.mdphantom.mdsiwx.mdscripts/siwx_build_message.jssiwx_send.jsDetails
From the project READMEBitrefill
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.
| If you detect | Read |
|---|---|
Claude Chat (show_widget or read_me, MCP on claude.ai) | claude-chat.md |
OpenClaw (~/.openclaw/, openclaw on PATH) | openclaw.md |
| Grok Bot or Cursor (Bot cloud computer; Cursor IDE, CLI or cloud agent) | grok-bot.md |
| Known host, need defaults | capability-matrix.md |
| Probe signals + derivation rules | decision-engine.md § Phase 1 |
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):
| Signal | Wallet doc |
|---|---|
| Signed-in Bitrefill + pre-funded balance | payment.md — balance + auto_pay |
Base MCP (get_wallets, sign, x402, send) | base-mcp.md; guest sign-in → siwx.md |
| AgentCash / CDP awal | agentcash.md, cdp-awal.md |
| Phantom / MetaMask (sign-only) | phantom.md, metamask.md |
| Ranking across wallets | matrix.md |
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 for autonomous buying — 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
| File | Use when |
|---|---|
| decision-engine.md | Capability probe + derivation |
| capability-matrix.md | Per-host exec / egress / ranked stacks |
| openclaw.md | OpenClaw Gateway — guest CLI via exec |
| claude-chat.md | claude.ai — MCP-first + show_widget |
Touchpoints
| File | Use when |
|---|---|
| mcp.md | Bitrefill MCP OAuth'd |
| x402.md | x402 REST via Base MCP or direct egress |
| cli.md | Shell + @bitrefill/cli ≥ 0.3.0 |
| cli-headless-auth.md | AgentMail / magic-link sign-in |
| api.md | v2 REST — Personal / Business / Affiliate |
| browse.md | Residential browser explore-only |
Wallets
| File | Use when |
|---|---|
| matrix.md | Wallet × touchpoint × HITL ranking |
| payment.md | Pay-time decision tree |
| base-mcp.md | Base MCP web_request, x402, send |
| siwx.md | Connect → JWT, redemption SIWX |
| agentcash.md | Autonomous x402 via fetch |
| cdp-awal.md | Coinbase Agentic Wallet / awal |
| metamask.md | MetaMask Agent Wallet (mm CLI) |
| phantom.md | Phantom MCP sign-only |
Cross-cutting
| File | Use when |
|---|---|
| safeguards.md | Spending policy + host hardening |
| troubleshooting.md | Errors across all paths |
Source of truth
Skill summarizes + routes. Exhaustive enums → https://docs.bitrefill.com.