x402-card

x402 仮想カードスキル

x402 HTTP 決済プロトコルを使用して、BSC 上の USDT でエージェント向けの使い捨て仮想デビットカード（Visa／Mastercard）を作成します。

⚡ ガス代の仕組み： BSC の USDT は EIP-3009 に対応していません。カード作成前に、クライアントがオンチェーントランザクションで一度だけ approve による承認を行う必要があります。実際の USDT 送金はサーバーが実行します。

• カード作成（x402）：アローワンスを確認 → 不足していて BNB がない場合は、WalletConnect 経由で 0.0003 BNB を自動送金して approve のガス代に充当 → USDT が不足している場合は USDT を自動送金 → EIP-712 署名（ガス代不要）→ サーバーが送金を送信（ガス代はサーバー負担）
• チャージ（topup）：WalletConnect のセッションは 1 回だけで、USDT をローカルウォレットに送金します。ユーザーはウォレットアプリで 1 件のトランザクションを承認します
• 出金（withdraw）：ローカルウォレットが ERC20 送金と BNB をオンチェーンで直接送信します。ガス代として BNB が必要です
• ガス代の補充（gas）：BNB のみを送金します（出金時に「No BNB for gas」と表示された場合、または BNB の追加が必要な場合に使用します）

---

開始時のメッセージ（必須）

このスキルを初めて使用するときは、必ず次の開始時のメッセージを出力してください。

まずツールを読み込み、既存の環境を確認します。

その後、直ちに「ステップ 1：事前チェック」に進みます。

---

コマンドの概要

すべての操作でグローバルコマンド x402-card を使用します。

📦 初回のみインストール：

npm install -g @aeon-ai-pay/x402-card@latest

npx ではなくグローバルコマンドを使用すると、コールドスタート時の 4～5 秒の遅延を避けられます。 アップグレード：npm update -g @aeon-ai-pay/x402-card。

x402-card setup --check                # Pre-check / auto-create wallet
x402-card setup --show                 # Show configuration
x402-card create --amount <usd> --poll # Create virtual card
x402-card status --order-no <orderNo>  # Query card status
x402-card wallet                       # Check local wallet balance
x402-card topup --amount <usdt>        # Top up USDT (WalletConnect, 1 confirmation)
x402-card gas [--amount <bnb>]         # Top up BNB for local wallet (WalletConnect, for approve/withdraw)
x402-card clean                        # Uninstall skill, clear cache
x402-card withdraw [--to <addr>] [--amount <usdt>]  # Withdraw funds

設定は ~/.x402-card/config.json に保存されます（ファイル権限は 600）。 ユーザーに秘密鍵を尋ねないでください。ローカルウォレットの秘密鍵は CLI が自動生成します。

---

ステップ 1：事前チェック（ウォレットの自動初期化）

ユーザーの意図にかかわらず、必ず最初に実行します。

x402-card setup --check

CLI の動作：

1. ~/.x402-card/config.json を読み込みます
2. privateKey がない場合 → viem.generatePrivateKey() で新しい秘密鍵をローカルに生成して保存します
3. JSON を返します：{ ready, created, mode, address, mainWallet, serviceUrl, amountLimits }

出力テンプレート

必ず最初に進捗メッセージを出力します。

> Pre-check in progress...

分岐 A：ウォレットがすでに存在する場合（ready: true、created: false）

0x0...{last4} Ready. Proceed to create a card for your agent.

分岐 B：今回自動作成した場合（ready: true、created: true）

Auto-creating your designated wallet...
0x0...{last4} Ready. Proceed to create a card for your agent.

• {last4} は返された address の末尾 4 文字です
• 後続の金額検証に備えて amountLimits.{min,max} を記録します
• 事前チェックはオフラインで行われます。オンチェーン残高の照会やサーバー呼び出しはありません

エッジケース

ユーザーの質問	回答
「自分のウォレットアドレスは何ですか？」	setup --check が返した address を表示します
「自分の秘密鍵をインポートしたいです」	対応していません。CLI はローカルウォレットを自動生成するだけです。カスタマイズするには、~/.x402-card/config.json を手動で編集してください
「ウォレットを復元できますか？」	できません。秘密鍵はローカルにのみ保存されます。資金を出金する前に、設定ファイルをバックアップしてください

---

ステップ 2：仮想カードの作成（残高不足時の自動チャージあり）

トリガー：ユーザーが仮想カードの購入／作成／取得を希望した場合。

2.0 金額の確認

• 金額は amountLimits.min ~ amountLimits.max の範囲内である必要があります（ステップ 1 の応答から取得し、ハードコードしないでください）
• ユーザーが金額を指定しない場合は、次の文面をそのまま使用してください（一字一句変更せず、変数の置換のみ可）：

  カードには最大 ${min}~${max} までチャージできます。いくらチャージしますか？

• ユーザーが金額を指定したら、直ちに実行します。2 回目の確認は不要です。2.1 に進みます。

2.1 作成の実行

x402-card create --amount <usd> --poll

CLI は内部で次の手順を実行します。

1. パラメーターと上限の検証
2. サーバーから支払い要件を取得（正確な USDT 金額）
3. 承認額を確認 → 不足していて、ローカルウォレットに BNB がない場合は、BNB が必要と判断
4. USDT 残高を確認 → 不足している場合は、チャージが必要と判断
5. チャージまたは BNB が必要な場合 → WalletConnect による入金を自動的に開始（QR ページを開き、ユーザーがウォレットアプリで承認するまで待機。タイムアウトは 5 分）
6. 入金完了後、自動的に処理を続行
7. approve による承認（オンチェーンのトランザクション。少量の BNB が必要です。初回利用時、または承認額が不足している場合のみ）
8. EIP-712 署名（ガス代不要）→ サーバーが実際の送金を実行
9. --poll を指定すると、最大 42 回ポーリング（最初の 5 回は 2 秒間隔、その後は 5 秒間隔）

最初の行に次の内容が出力されます。

> Creating Agent Card...

⚠️ create コマンドには対話型の WalletConnect フロー（残高不足時）が含まれるため、フォアグラウンドで同期実行する必要があります。

• run_in_background: true を使用しないでください
• ユーザーがスキャンを完了する前にプロセスを終了しないでください

🔧 誤って create をバックグラウンドで実行し、終了させてしまった場合： ユーザーのオンチェーントランザクションはすでに送信されている可能性があります（USDT が実際にローカルウォレットに届いている可能性があります）。 この場合、再チャージしないでください。代わりに次の手順を実行します。

1. x402-card wallet を実行して、USDT が届いていることを確認します
2. 届いている場合は、元の create --amount <usd> --poll を再実行します
3. 届いていない場合（ユーザーが実際にはスキャンしていない場合）は、create をフォアグラウンドで再実行します

2.2 シナリオ別の分岐

ケース A：金額が範囲外

CLI は次の内容を返します。

{"error":"Amount must be at least $0.6 ...","min":0.6,"max":800}

有効な範囲をユーザーに提示し、新しい金額を尋ねます。

ケース B：作成成功

CLI は success: true と orderNo を含む JSON を出力します。

カードの詳細の取得には約 30 秒かかる場合があります。まず、次の待機メッセージを出力します。

> Fetching card details, please wait...

詳細が返されたら、次の内容を表示します（文面はそのまま使用し、変数の置換のみ行ってください）。

Order No: {orderNo}
Card: {cardScheme} •••• {last4}
State: Active
Remaining balance: ${amount} USD
Usage: 0 / 1 (single-use)

必ず orderNo を記録してください。以降のステータス照会で使用する唯一の識別子です。

ケース C：入金署名のタイムアウト（5 分）

CLI は次の内容を返します。

{"error":"Payment approval timed out. Please try again."}

ユーザーに伝え、再試行するかどうか尋ねます。自動的に再試行しないでください。

ケース C.1：ユーザーが署名を拒否

CLI は次の内容を返します。

{"error":"Payment approval was rejected. Please try again if you'd like to proceed."}

ユーザーに伝えてください。自動的に再試行しないでください。

ケース C.2：入金後も残高不足

CLI は Still insufficient USDT after funding エラーを返します。ユーザーに伝えてください。

ケース D：サーバーのネットワーク／呼び出しエラー

CLI は HTTP エラーとともに success: false を返します。未加工のエラーを表示し、後でもう一度試すか serviceUrl を確認するようユーザーに案内します。

ケース E：ポーリングのタイムアウト（--poll が 42 回に達した場合）

CLI は次の内容を出力します。

Polling timeout after 42 attempts. Check manually with: x402-card status --order-no {orderNo}

カードの処理がまだ続いていることをユーザーに伝えます。orderNo を記録し、後でステップ 3 を使って照会するよう伝えてください。ポーリングを続けないでください。

フィールドの詳細については、create-card を参照してください。

---

ステップ 3：カードのステータスを照会

トリガー：ユーザーがカードのステータスを確認／照会したい場合。

3.1 コマンド

x402-card status --order-no <orderNo>
x402-card status --order-no <orderNo> --poll  # Poll until terminal status

3.2 出力テンプレート

> Fetching card status...

Card: {cardScheme} •••• {last4}
State: {Active | Used | Expired | Pending | Failed}
Remaining balance: ${balance} USD
Usage: {used} / {total} (single-use)

3.3 例外ケース

シナリオ	対応
ユーザーが orderNo を持っていない	直近の create 出力に含まれる orderNo を尋ねます。確認できない場合は、照会できないことを伝えます
orderNo が無効／サーバーの応答が空	未加工のエラーを表示し、orderNo を確認するようユーザーに案内します
ステータスが Pending	カードの処理がまだ続いていることを伝えます。必要に応じてポーリングできますが、42 回を超えないようにします
ステータスが Failed	失敗理由を表示します。注文は無効なため、再度 create を実行する必要があります

フィールドの詳細については、check-status を参照してください。

---

ステップ 4：ウォレット管理

トリガー：ユーザーが残高の確認／チャージ／出金をしたい場合。

4.1 ローカルウォレットの残高を確認

x402-card wallet

ローカルウォレットの USDT 残高とアドレスが表示されます。以前に topup を使用している場合は、メインウォレットの残高も表示されます。

4.2 チャージ

x402-card topup --amount <usdt>               # Top up USDT to local wallet

topup は WalletConnect 経由でメインウォレットからローカルウォレットに USDT を送金します。ユーザーはウォレットアプリで 1 件のトランザクションを承認します。

💡 BNB を別途チャージする必要はありません。create コマンドは、許可額が不足していて BNB がないことを検知すると、0.0003 BNB を自動的にリクエストします。

4.3 メインウォレットへの出金

x402-card withdraw                                  # Withdraw all USDT to recorded mainWallet
x402-card withdraw --amount <usdt>                  # Specify amount
x402-card withdraw --to 0xMainWallet                # Specify destination address
x402-card withdraw --to 0xMainWallet --amount <usdt>

⚠️ 出金にはガス代として BNB が必要です： x402 カードの作成（ガス代不要）とは異なり、withdraw はローカルウォレットから直接オンチェーンで ERC20 を送金するため、 ローカルウォレット自身が BNB でガス代を支払う必要があります（0.0005 BNB 以上を推奨）。 ユーザーは取引所または自身のウォレットから、ローカルウォレットのアドレスに少額の BNB を送金する必要があります。

送金先アドレスの解決優先順位

1. CLI 引数 --to <address>
2. ~/.x402-card/config.json の mainWallet（ユーザーが topup を実行した後にのみ利用可能）

出力テンプレート（文言は一字一句そのまま使用すること。変数置換のみ）

> Reclaiming funds...

From: 0x0...{session_last4}
To: main wallet (0x0...{main_last4})

Amount: {amount} USDT
Status: completed

「main wallet」という表記は仕様上必須です。省略しないでください。括弧内のアドレスで、ユーザーは送金先を確認できます。

エッジケース

エラー	意味	対応
No main wallet address found. Use --to <address>	config に mainWallet がなく、--to も指定されていません	ユーザーに送金先アドレスを指定するよう依頼します
No USDT to withdraw.	ローカルウォレットの USDT 残高が 0 です	出金可能な資金がないことを伝え、まず topup を実行するよう提案します
No BNB for gas. ...	ローカルウォレットに BNB がなく、ガス代を支払えません	WalletConnect 経由で BNB をチャージするため、ユーザーに x402-card gas の実行を促します。4.4 を参照してください
Requested X USDT but only Y available	--amount が実際の残高を超えています	実際の残高を表示し、新しい金額を確認するようユーザーに依頼します
Withdraw failed: ...	オンチェーンのトランザクションに失敗しました	エラーをそのまま表示し、後でもう一度試すよう提案します

4.4 ローカルウォレットのガス代をチャージ（BNB）

withdraw が No BNB for gas を報告した場合、または追加の BNB が必要な場合は、専用の gas サブコマンドを使用して、WalletConnect 経由でメインウォレットから少額の BNB を送金します。

x402-card gas                    # Default 0.001 BNB
x402-card gas --amount 0.002     # Custom amount

⚠️ このコマンドでは WalletConnect の対話型フローを使用します（topup と同じ仕組みです）：

• ターミナルに QR コードと wc: URI が表示されます
• ユーザーはウォレットアプリでスキャンしてメインウォレットを接続します
• ウォレットで 1 件の BNB 送金を承認します（金額 = <amount>、送金先 = ローカルウォレット）
• 最大待機時間は 5 分です。バックグラウンドで実行してはいけません

成功すると、mainWallet が config に自動保存されます（以降の withdraw では --to を省略できます）。

出力テンプレート

> Topping up gas...
Initializing WalletConnect session...
Waiting for wallet confirmation...
BNB transfer confirmed.

Local wallet: 0x0...{last4}
Balance: {bnb} BNB

エッジケース

エラー	対応
Transaction rejected in wallet.	キャンセルされたことをユーザーに伝え、再試行するか確認します。自動で再試行してはいけません
BNB transfer failed: ...	メインウォレットの BNB 不足、またはオンチェーンでのリバートです。まずメインウォレットに BNB を用意するようユーザーに促します
WalletConnect の 5 分間のタイムアウト	タイムアウトしたことをユーザーに伝え、gas を再実行するよう提案します

---

意図に応じたコマンドの選択

ユーザーの意図	実行するコマンド
初回の利用／状態が不明	setup --check
現在の config／ウォレットアドレスを確認	setup --show
バーチャルカードを作成	create --amount <n> --poll
セッションキーの USDT が不足しているためチャージ	topup --amount <n>
カードのステータスを確認	status --order-no <n>
ローカルウォレットの残高を確認	wallet
メインウォレットに出金	withdraw [--to <addr>] [--amount <n>]
ローカルウォレットの BNB をチャージ（出金前）	gas [--amount <bnb>]
x402 プロトコルについて確認	x402-protocol を読む
購入できるもの／利用できる機能を確認	store を読む

---

表記の一貫性に関する制約（必読）

以下の重要なフレーズと行単位の出力テンプレートは、言い換えや翻訳、文字の追加・削除（句読点、スペース、> 接頭辞、大文字・小文字の区別を含む）をせず、一字一句そのまま使用する必要があります。

行単位のテンプレート（完全一致必須）

ステップ	テンプレートの最初の行
事前チェック	> Pre-check in progress...
ウォレットの自動作成	Auto-creating your designated wallet...
ウォレット準備完了	0x0...{last4} Ready. Proceed to create a card for your agent.
カード作成	> Creating Agent Card...
作成成功	Order No: {orderNo} + カードの詳細（ケース B を参照）
署名タイムアウト	Payment approval timed out. Please try again.
署名拒否	Payment approval was rejected. Please try again if you'd like to proceed.
資金投入フロー	> Funding flow triggered...
カード詳細の取得	> Fetching card details, please wait...
ステータスの照会	> Fetching card status...
資金の引き出し	> Reclaiming funds...
引き出し先の行	To: main wallet (0x0...{last4})
引き出しステータスの行	Status: completed

重要なフレーズ（そのまま保持すること）

• Fetching card details, please wait...
• Virtual card ready with, loaded!
• Payment approval timed out. Please try again.
• Payment approval was rejected. Please try again if you'd like to proceed.
• Card, State, Remaining balance, Usage, single-use
• From, To, Amount, Status, completed
• main wallet（引き出し先の行のリテラルテキスト）

変数の対応

プレースホルダー	ソース
{last4}	setup --check / wallet / withdraw の出力にある address の末尾4文字
{required}	create のエラーレスポンスにある required フィールド
{available}	create のエラーレスポンスにある available フィールド、または topup エラーに明示された値
{amount}	withdraw の出力にある withdrawn フィールド
{orderNo}	create の出力にある orderNo フィールド

禁止されている逸脱

• ❌ 他の言語に翻訳する（例：中国語の「余额检查：不足」）
• ❌ 大文字と小文字を変更する（例：「Balance Check」）
• ❌ 省略する（例：「BNB insuff.」）
• ❌ 装飾を追加する（例：絵文字、太字、✅）
• ❌ 行を分割または結合する
• ❌ 類義語に置き換える（例：insufficient を not enough に置き換える）

---

全般的な禁止事項

• 絶対にユーザーに秘密鍵を尋ねないでください。ローカルウォレットは CLI によって自動生成されます
• ユーザーが金額を確認する前に、絶対に create または topup を実行しないでください
• 絶対に秘密鍵全体を記録または表示しないでください。アドレスは 0x0...last4 形式で表示します
• 絶対に setup --check を省略して、他のコマンドを直接実行しないでください
• 絶対に WalletConnect フローを伴う create / topup / gas / その他のコマンドをバックグラウンドで実行しないでください（フォアグラウンドで同期的に実行する必要があります）。誤ってバックグラウンドで実行したことが原因の「支払い済みだが検出されない」問題については、ステップ 2.1 の復旧手順に従ってください
• 資金投入または署名の失敗後に自動で再試行しないでください。エラーをユーザーに伝え、停止してください
• status のポーリングは42回を超えて行わないでください。タイムアウトしたら停止し、手動照会用に orderNo を控えるようユーザーに促してください
• amountLimits を捏造しないでください。常に setup --check が返す min/max を使用してください