cryptorefills-buy

Cryptorefills Buy — MCP 購入ワークフロー

購入の全工程に対応します：検索、価格確認、検証、注文、支払い、配送状況の追跡。すべての暗号資産決済方法、固定価格と金額範囲指定の商品、複数商品のカート、対話形式の購入ガイドに対応しています。

閲覧のみの場合は、cryptorefills-catalog の手順に従ってください。 Base 上の USDC を使って自律型エージェントが購入する場合（アカウント不要）は、代わりに cryptorefills-x402 に従ってください。

人の決済操作なしで、ウォレットを使った自律的な購入が必要な場合は、cryptorefills-x402 のスキル手順に切り替えてください。

有効化する条件

• 暗号資産でギフトカードを購入する、電話にチャージする、または eSIM を取得したい場合
• Bitcoin、Lightning、Ethereum、Solana、USDC、USDT、Litecoin、Dogecoin、TON、SUI、その他の暗号資産で支払いたい場合
• Cryptorefills で注文または購入を完了したい場合
• 注文状況の確認や配送状況の追跡をサポートする必要がある場合
• キーワード：「暗号資産でギフトカードを購入」、「bitcoin で支払う」、「ethereum で支払う」、「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 を呼び出す前にユーザーの明示的な承認を待ってください。

• セッションごとの支出上限を設定（既定値：1 セッションあたり最大 $100、1 取引あたり最大 $50。ユーザーが明示的に希望した場合のみ引き上げてください）し、注文全体の累積支出を追跡してください
• createOrder の前に getProductPrice から提示された価格を確認してください
• デジタル商品は配送後に返金できません
• ギフトカードコードは現金同様です。安全に保管し、公開したりファイルに書き込んだりしないでください
• ユーザーがコードを利用するまでメモリ内に保持してください
• 購入ごとに、注文 ID、商品、金額、決済方法を記録してください
• エージェントによる購入には、残高を制限した専用ウォレットを使用してください
• 利用規約：https://www.cryptorefills.com/terms/

基本ワークフロー

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

購入方法は 2 つあります：

1. 手動フロー — 検索 → 価格確認 → 検証 → 作成 → 追跡（すべてを制御できます）
2. ガイド付きフロー — purchaseElicitation が対話形式で購入手順を案内します（会話型エージェントにおすすめです）

手順：手動フロー

1. 検索／発見

searchProducts または listBrands を使って商品を検索します。

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

注： 検索パラメーターは query ではなく q、言語パラメーターは language ではなく lang です。

国コードには、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）を提示します。ウォレットはこのURIを直接解析できます。リッチな環境では、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で始まる場合は、アクセス先のURLです。プレーンテキストの場合は、手動で利用するコードです。
• モバイルチャージ：電話番号に自動的にチャージされます。渡すコードはありません。
• eSIM：QRコードとアクティベーション手順は注文の詳細にあります。

実例（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は、エージェントが購入プロセス全体を進められるよう案内する、対話型のステートフルなツールです。対話型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 の範囲内である必要があります。範囲外の金額は拒否されます
• 事前検証：エラーを見つけるため、createOrder の前に必ず validateOrder を呼び出してください
• 支払いのタイムアウト：Lightning は約 15 分、オンチェーンは約 60～180 分です。有効期限が切れた場合は、新しい注文を作成してください
• WaitingForManualAction：Cryptorefills のサポートが確認中であることを示します。ユーザーに伝えて、完了を待ってください
• カートの上限：createOrder の呼び出し 1 回につき、最大 10 件までです。それを超える注文は複数回に分けてください
• 価格表示の通貨：価格は法定通貨で表示され、支払いは固定された為替レートで暗号資産を使用します

参考資料

このスキルファイルに記載されている情報より詳しい内容が必要な場合にのみ、参考資料を読み込んでください。

ファイル	読み込むタイミング	内容
references/mcp-tools.md	特定の MCP ツール呼び出しで、正確なパラメータースキーマが必要な場合	10 種類すべての MCP ツールのシグネチャとパラメーター
references/payment-methods.md	特定のチェーン、ネットワーク、または支払いルーティングについてユーザーから質問された場合	対応する暗号資産、チェーン、支払いフロー
references/order-lifecycle.md	注文が想定外の状態になった場合、または配送やポーリングの詳細が必要な場合	注文と支払いの状態遷移、配送タイプ
references/troubleshooting.md	ツール呼び出しでエラーが返された場合、または注文が停滞している場合	よくあるエラーと復旧手順