bitrefill

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.

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
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 — 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.