cryptorefills-buy

Cryptorefills 购买 — MCP 购买工作流

完整的购买流程：搜索、查询价格、验证、下单、付款、跟踪配送。支持所有加密货币支付方式、固定金额和区间金额商品、多商品购物车，以及交互式引导购买。

仅浏览时，请按照 cryptorefills-catalog 中的说明操作。 使用 Base 上的 USDC 进行自主 Agent 购买时（无需账户），请改为按照 cryptorefills-x402 中的说明操作。

当用户需要在无需人工参与支付的情况下通过自主钱包购买时，请切换到 cryptorefills-x402 技能说明。

何时启用

• 用户想用加密货币购买礼品卡、为手机充值或获取 eSIM
• 用户提到使用 Bitcoin、Lightning、Ethereum、Solana、USDC、USDT、Litecoin、Dogecoin、TON、SUI 或其他加密货币付款
• 用户想在 Cryptorefills 下单或完成购买
• 用户需要帮助查询订单状态或跟踪配送
• 关键词：“用加密货币购买礼品卡”“用比特币付款”“用以太坊付款”“用 Solana 付款”“购买 eSIM”“用 USDC 为手机充值”“用 USDT 购买”“用 Litecoin 付款”“用 Dogecoin 付款”

要求

• MCP 客户端已连接到 https://api.cryptorefills.com/mcp/http
• 必需的请求头：User-Agent: Cryptorefills-MCP/1.0
• 用于付款的加密钱包
• 无需 Cryptorefills 账户或 API 密钥

要在 Claude Code 中配置 MCP 连接：

{
  "mcpServers": {
    "cryptorefills": {
      "url": "https://api.cryptorefills.com/mcp/http",
      "headers": { "User-Agent": "Cryptorefills-MCP/1.0" }
    }
  }
}

支出保护措施

购买前务必确认。 呈现商品名称、面额、价格和支付方式；在调用 createOrder 前等待用户明确批准。

• 设置单次会话支出限额（默认：每次会话最高 $100，每笔交易最高 $50；仅在用户明确要求时提高），并跟踪所有订单的累计支出
• 在调用 createOrder 前，通过 getProductPrice 核实报价
• 数字商品一经交付，概不退款
• 礼品卡代码类似现金，应安全保存，切勿公开分享或写入文件
• 将代码保存在内存中，直到用户兑换
• 记录每笔购买：订单 ID、商品、金额、支付方式
• 使用余额有限的专用钱包进行 Agent 发起的购买
• 条款：https://www.cryptorefills.com/terms/

核心工作流

searchProducts → getProductPrice → validateOrder → createOrder → getOrderStatus
         │                                              │
         └── or use purchaseElicitation ────────────────┘

有两种购买方式：

1. 手动流程 — 搜索 → 查询价格 → 验证 → 创建订单 → 跟踪（全面掌控）
2. 引导式流程 — purchaseElicitation 交互式引导完成购买（推荐用于对话式 Agent）

分步说明：手动流程

1. 搜索 / 发现

使用 searchProducts 或 listBrands 查找商品。

searchProducts(country_code="US", q="Netflix")

注意：搜索参数是 q（不是 query），语言参数是 lang（不是 language）。

国家代码必须使用大写的 Alpha-2 ISO 代码（US、IT、BR）。注意：x402 技能使用小写字母，属于不同的端点。

2. 获取价格

固定面额商品（is_dynamic: false）：价格已包含在 listProductsForCountry 的响应中（coin_amount 字段），无需额外调用。

区间金额商品（is_dynamic: true）：使用 getProductPrice 获取指定金额在区间内的价格。

getProductPrice(brand_name="Amazon.com", country_code="US", face_value=75, coin="USDC")

face_value 是数字（75），不是字符串。返回包含精确加密货币价格的 coin_amount。

3. 验证订单

创建订单前，使用 validateOrder。validateOrder 和 createOrder 都使用包含 payment 和 deliveries 的 body 包装对象。

validateOrder(body={
  payment: {type: "via", payment_via: "USER_WALLET", coin: "BTC", network: "Mainnet"},
  deliveries: [{
    denomination: "25 USD",
    brand_name: "Steam",
    beneficiary_account: "[email protected]",
    country_code: "US"
  }]
})

关键字段：

• payment.type — 加密货币付款时始终为 "via"
• payment.payment_via — 来自 getPaymentViasWithCurrencies（例如，"USER_WALLET"）
• payment.coin — 加密货币（例如，"BTC"、"USDC"）
• payment.network — 使用 getPaymentViasWithCurrencies 中的确切字符串。常见值：

币种	network 值
BTC	Mainnet
ETH	ETH Mainnet
USDC	Base、Polygon (Matic)、Solana、Arbitrum
USDT	Polygon (Matic)、Tron
SOL	Solana

• deliveries[].denomination — 固定商品：使用 listProductsForCountry 中的确切字符串（例如，"25 USD"）。区间商品：使用字面字符串 "range"（并通过 product_value 指定所需金额）
• deliveries[].brand_name — 使用 listBrands 中的确切品牌名称
• deliveries[].beneficiary_account — 礼品卡/eSIM 填写电子邮件地址，手机充值填写 E.164 格式的电话号码
• deliveries[].country_code — 大写的 Alpha-2 代码

及早发现错误：电话号码无效、金额超出范围、商品不可用、订单金额低于最低要求。

4. 创建订单

使用与 validateOrder 相同的 body 架构，此外还必须提供 user.email。

createOrder(body={
  user: {email: "[email protected]"},
  payment: {type: "via", payment_via: "USER_WALLET", coin: "BTC", network: "Mainnet"},
  deliveries: [{
    denomination: "25 USD",
    brand_name: "Steam",
    beneficiary_account: "[email protected]",
    country_code: "US"
  }]
})

返回：order_id、wallet_address、coin_amount、qr_url、qr_text（付款 URI）、payment_state、order_state。

向用户展示付款信息：在纯文本环境中，展示 qr_text 付款 URI（例如，bitcoin:3EFu...?amount=0.00038）——钱包可以直接解析。在富文本环境中，提供 qr_url 图片的链接或直接显示图片。

多商品订单：在 deliveries 数组中最多添加 10 件商品。每件商品可以属于不同品牌、国家或配送类型。

5. 跟踪订单

使用订单 ID 轮询 getOrderStatus。

• 轮询间隔：每 30 秒
• 付款状态：WalletCreated → PaymentRequested → PaymentReceived（或 Expired）
• 订单状态：WaitingForPayment → Done（成功）/ Expired / Canceled / WaitingForManualAction
• 付款时限：Lightning 发票约 15 分钟后过期。链上付款会在约 60–180 分钟后过期，具体取决于方式。

订单达到终止状态后停止轮询。

6. 交付

订单状态为 Done 时：

• 礼品卡：代码/PIN 位于 deliverable.pin_code。如果以 http/https 开头，则是需要访问的网址。纯文本则是需要手动兑换的代码。
• 手机充值：自动充值到相应电话号码。无需交付代码。
• eSIM：二维码和激活说明位于订单详情中。

操作示例（3 种商品类型）

示例 A：礼品卡 — 美国 Steam 25 美元（BTC）

1. searchProducts(country_code="US", q="Steam")
   → finds brand "Steam", category "games"

2. listProductsForCountry(country_code="US", brand_name="Steam", coin="BTC")
   → products: [{product_id: "a300c244-...", denomination: "25 USD", coin_amount: "0.00038", is_dynamic: false}]

3. validateOrder(body={
     payment: {type: "via", payment_via: "USER_WALLET", coin: "BTC", network: "Mainnet"},
     deliveries: [{denomination: "25 USD", brand_name: "Steam", beneficiary_account: "[email protected]", country_code: "US"}]
   })
   → coin_amount: "0.00038", problems: [] (valid)

4. createOrder(body={
     user: {email: "[email protected]"},
     payment: {type: "via", payment_via: "USER_WALLET", coin: "BTC", network: "Mainnet"},
     deliveries: [{denomination: "25 USD", brand_name: "Steam", beneficiary_account: "[email protected]", country_code: "US"}]
   })
   → order_id: "e054...", wallet_address: "3EFu...", coin_amount: "0.00038", qr_text: "bitcoin:3EFu...?amount=0.00038"

5. getOrderStatus(order_id="e054...")
   → payment_state: "PaymentRequested", order_state: "WaitingForPayment"

示例 A2：区间礼品卡 — 美国 Amazon.com 50 美元（Base 上的 USDC）

1. searchProducts(country_code="US", q="Amazon")
   → finds brand "Amazon.com", is_dynamic: true, range $5–$500

2. getProductPrice(brand_name="Amazon.com", country_code="US", face_value=50, coin="USDC")
   → coin_amount: "51.08", product_id: "5549e92e-..."

3. validateOrder(body={
     payment: {type: "via", payment_via: "USER_WALLET", coin: "USDC", network: "Base"},
     deliveries: [{denomination: "range", brand_name: "Amazon.com", beneficiary_account: "[email protected]", country_code: "US", product_value: "50"}]
   })
   → coin_amount: "51.08", problems: [] (valid)
   → Note: denomination is "range" (literal string), product_value is "50" (desired amount)

4. createOrder(body={
     user: {email: "[email protected]"},
     payment: {type: "via", payment_via: "USER_WALLET", coin: "USDC", network: "Base"},
     deliveries: [{denomination: "range", brand_name: "Amazon.com", beneficiary_account: "[email protected]", country_code: "US", product_value: "50"}]
   })
   → order_id, wallet_address (USDC on Base), coin_amount: "51.08"

示例 B：手机充值 — 巴西 Claro 15 BRL（Base 上的 USDC）

1. searchProducts(country_code="BR", q="Claro")
   → finds brand "Claro Credits", category "mobile_credits"

2. listProductsForCountry(country_code="BR", brand_name="Claro Credits", coin="USDC")
   → products: [{denomination: "15 BRL", delivery_type: "by_phone", is_dynamic: false}]

3. validateOrder(body={
     payment: {type: "via", payment_via: "USER_WALLET", coin: "USDC", network: "Base"},
     deliveries: [{denomination: "15 BRL", brand_name: "Claro Credits", beneficiary_account: "+5511999887766", country_code: "BR"}]
   })
   → Note: beneficiary_account is the E.164 phone number (not email)

4. createOrder(body={
     user: {email: "[email protected]"},
     payment: {type: "via", payment_via: "USER_WALLET", coin: "USDC", network: "Base"},
     deliveries: [{denomination: "15 BRL", brand_name: "Claro Credits", beneficiary_account: "+5511999887766", country_code: "BR"}]
   })
   → order_id, wallet_address (USDC on Base), coin_amount

示例 C：eSIM — 意大利流量套餐（ETH）

1. searchProducts(country_code="IT", q="eSIM")
   → finds brand "eSIM", category "e-sim"

2. listProductsForCountry(country_code="IT", brand_name="eSIM", coin="ETH")
   → products: [{denomination: "1 GB 7 days", delivery_type: "by_email", is_dynamic: false}]

3. validateOrder(body={
     payment: {type: "via", payment_via: "USER_WALLET", coin: "ETH", network: "ETH Mainnet"},
     deliveries: [{denomination: "1 GB 7 days", brand_name: "eSIM", beneficiary_account: "[email protected]", country_code: "IT"}]
   })
   → Note: denomination is "1 GB 7 days" (exact string from listProductsForCountry), beneficiary is email

4. createOrder(body={
     user: {email: "[email protected]"},
     payment: {type: "via", payment_via: "USER_WALLET", coin: "ETH", network: "ETH Mainnet"},
     deliveries: [{denomination: "1 GB 7 days", brand_name: "eSIM", beneficiary_account: "[email protected]", country_code: "IT"}]
   })
   → order_id, wallet_address (ETH), coin_amount, qr_text

分步操作：引导式信息收集

purchaseElicitation 是一个交互式、有状态的工具，可引导 Agent 完成整个购买流程，特别适用于对话式 UI。

1. 使用空的 body {} 调用 purchaseElicitation（可选传入 lang 以使用本地化提示词）——接收一个 session_token
2. 服务端会返回一个问题（例如，“哪个国家？”、“哪个品牌？”、“什么面额？”）
3. 使用 session_token 将用户的回答传回
4. 重复上述步骤，直到 status 等于 complete（订单已创建）或 error
5. 如果用户改变主意，可使用 action: "back" 返回上一步

信息收集流程会在内部处理商品选择、面额、配送信息和付款方式选择。这是从表达购买意图到完成购买的最简单途径。

关键注意事项

• 电话号码：必须使用 E.164 格式——以 + 开头，包含国家代码和号码，不含空格或连字符
• 国家代码：MCP 工具要求使用大写（US，而不是 us）。x402 技能使用小写
• 国家匹配：产品所属国家必须与收件人兑换产品的国家一致
• 金额范围：必须处于 min_value 和 max_value 之间。超出范围的金额会被拒绝
• 先进行验证：始终先调用 validateOrder，再调用 createOrder，以便发现错误
• 支付超时：Lightning 约 15 min，链上支付约 60–180 min。若订单过期，请创建新订单
• WaitingForManualAction：表示 Cryptorefills 支持团队正在审核——请告知用户并等待
• 购物车限额：每次调用 createOrder 最多包含 10 件商品。更多商品请拆分为多次调用
• 定价中的货币：价格以法定货币报价；支付时按锁定的汇率使用加密货币

参考资料

只有在需要了解本技能文件未涵盖的详细信息时，才加载参考资料。

文件	加载时机……	内容
references/mcp-tools.md	需要特定 MCP 工具调用的准确参数架构时	全部 10 个 MCP 工具签名及其参数
references/payment-methods.md	用户询问特定链、网络或支付路由时	支持的加密货币、链和支付流程
references/order-lifecycle.md	订单进入意外状态，或需要了解交付／轮询详情时	订单和支付状态机、交付类型
references/troubleshooting.md	工具调用返回错误或订单卡住时	常见错误及恢复步骤