bitrefill

Bitrefill

数字商品（礼品卡、手机充值、eSIM）——覆盖 180 多个国家，1,500 多个品牌。支付方式：加密货币、Lightning、USDC x402、预充值余额。

根据 执行环境 × 钱包 × 交互入口 选择路径——检测每一层，阅读对应指南，然后选择符合需求且人工介入最少的技术栈。

面向用户的语言

采用礼宾式语气——让加密货币支付像购买礼品卡，而不是转账到钱包。适用于所有可见界面：助手消息、思考摘要、工具调用标题。全程使用用户的语言——本地化所有文案；不要在意大利语（或其他语言）的会话中原封不动地贴上英文模板。

可以说：“我来为你查找这张礼品卡” · “使用你的 Base 钱包登录一次” · “在你的 Base Account 中批准付款” · “你的兑换码已准备就绪。”

**切勿说：**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——也不要提及内部工具或路径名称。

内部用语	改用以下说法
connect / SIWX / JWT	“使用你的 Base 钱包登录一次”（免费——仅用于浏览）
search / detail	“正在搜索 [product]……”
invoice/create	“[Product] — [amount]：共计 [total] USDC。确认吗？”
invoice/pay / x402 pay	“在你的 Base Account 中批准付款”
poll / delivery	“你的兑换码已准备就绪。”

**流程：**用户可见消息不超过 4 条——(1) 说明目标，并在需要时请求首次批准；(2) 价格详情并确认；(3) 批准付款；(4) 交付。在用户操作关口之间，只调用工具——除非遇到阻塞或错误，否则不发送状态消息。静默决定路由；开场说明目标，而非流程；每项信息只说一次；静默轮询（绝不要求用户提醒你）。

**付款详情（单条消息）：**商品 · 面值 · 准确的 USDC 总额（网络）· 余额 · 有效期 · 必要时用一句话说明汇率。**交付：**提供兑换码，并中性说明商品不可退款。

参考文档横幅（原样复制到每份指南的顶部）：内部机制——绝不可对用户说出。以日常购物用语表达／思考／命名工具：“使用你的钱包登录”“批准付款”“你的兑换码已准备就绪”；绝不提及 x402 / SIWX / JWT / path / endpoint。

如果缺少 Bitrefill 登录，但 Base 钱包可用：登录钱包一次，然后浏览，再批准付款一次——不要每次搜索都单独收取费用。特定主机的文案 → claude-chat.md § 用户语气。

如何选择路由

安全措施 → safeguards.md。然后分三个阶段——采取行动前，先阅读每一层对应的指南：

1. 检测执行环境 → 阅读执行环境说明

探测当前所在的主机环境（exec/shell、出站网络、MCP 连接器、浏览器、生成式 UI）。匹配相应配置，然后打开该执行环境文档——其中的说明优先于通用默认设置。

如果检测到	阅读
Claude Chat（show_widget 或 read_me，claude.ai 上启用了 MCP）	claude-chat.md
OpenClaw（~/.openclaw/、PATH 中有 openclaw）	openclaw.md
Grok Bot 或 Cursor（Bot 云端计算机；Cursor IDE、CLI 或云端 Agent）	grok-bot.md
已知主机，需要默认设置	capability-matrix.md
探测信号及推导规则	decision-engine.md § 阶段 1

执行环境文档会说明哪些操作禁止进行（例如 Claude Chat 中不能使用 CLI、不能在沙箱中使用 curl 等），以及适用于特定主机的排序技术栈。

2. 检测钱包 → 阅读钱包说明

探测本次会话中可用的支付能力（与目录渠道无关）：

信号	钱包文档
已登录 Bitrefill + 预充值余额	payment.md — balance + auto_pay
Base MCP（get_wallets、sign、x402、send）	base-mcp.md；访客登录 → siwx.md
AgentCash / CDP awal	agentcash.md、cdp-awal.md
Phantom / MetaMask（仅签名）	phantom.md、metamask.md
钱包排名	matrix.md

完整探测列表 → decision-engine.md § 阶段 2。

3. 为此场景选择接入点 × 钱包

综合考虑运行环境限制、钱包可用性和意图（浏览还是购买；Bitrefill 账户还是访客 USDC）。选择仍可用且人工介入程度最低的方案栈，然后阅读接入点文档并执行。

接入点（目录/结账渠道 — 首个可行匹配项）：

如果	阅读
search-products / buy-products 可见（OAuth 或 API 密钥）	mcp.md
Base MCP web_request + 访客 USDC，无 Bitrefill 账户	x402.md — 钱包登录（路径 1），而非按调用付费
Shell + npm，无 Bitrefill MCP	cli.md
仅限直接 HTTP	api.md
仅浏览 + 居民浏览器	browse.md
均不可行	向用户发送 bitrefill.com 链接

支付时使用的钱包 — 为所选接入点挑选最佳可用钱包 → payment.md、matrix.md。典型搭配：

接入点	优先使用的钱包
Bitrefill MCP	balance + auto_pay → Base MCP 支付 → 支付链接
访客结账（x402 REST）	AgentCash / awal → Base MCP 登录 + 支付 → 登录可用时，切勿在浏览时按调用付费
CLI	在 buy-products 时使用上述同一钱包排名

冲突解决 + 全局排名 → decision-engine.md § 阶段 3。

最高级别的支出保障措施

涉及真实资金的交易。 兑换码即时生成；数字商品一经交付，概不退款。

• 购买前确认，除非用户已在本次会话中选择自主购买。
• 兑换码 = 现金 — 切勿粘贴到公开渠道；优先保存在内存中。
• 自主购买使用专用低余额账户 — 切勿向 Agent 提供钱包助记词。技能不是钱包。
• 记录每笔购买 — invoice_id、商品、金额、支付方式。

完整保障措施 + 按主机加固 → safeguards.md。

参考资料

运行环境

文件	适用场景
decision-engine.md	能力探测 + 推导
capability-matrix.md	各主机的执行 / 出站能力 / 排名方案栈
openclaw.md	OpenClaw Gateway — 通过 exec 使用访客 CLI
claude-chat.md	claude.ai — MCP 优先 + show_widget

接入点

文件	适用场景
mcp.md	已完成 OAuth 认证的 Bitrefill MCP
x402.md	通过 Base MCP 或直接出站访问使用 x402 REST
cli.md	Shell + @bitrefill/cli ≥ 0.3.0
cli-headless-auth.md	AgentMail / magic-link 登录
api.md	v2 REST — Personal / Business / Affiliate
browse.md	仅通过居民浏览器进行探索

钱包

文件	适用场景
matrix.md	钱包 × 触点 × HITL 排名
payment.md	支付时决策树
base-mcp.md	Base MCP web_request、x402、send
siwx.md	连接 → JWT、兑换 SIWX
agentcash.md	通过 fetch 实现自主 x402
cdp-awal.md	Coinbase Agentic Wallet / awal
metamask.md	MetaMask Agent Wallet（mm 命令行）
phantom.md	Phantom MCP 仅签名

跨领域

文件	适用场景
safeguards.md	支出策略 + 主机加固
troubleshooting.md	所有路径中的错误

事实来源

Skill 负责归纳 + 路由。详尽的枚举 → https://docs.bitrefill.com。