verify402

verify402-mcp

verify402 向け MCP サーバーです。エージェントが支払いまたはチェーントランザクションに署名する前に実行する、無料でフェイルクローズ方式の事前チェックゲートと、x402 経由で呼び出しごとに支払うオンチェーンチェック 5 種類を提供します。

Claude Desktop、Cursor、OpenCode、および stdio に対応する任意の MCP クライアントで動作します。無料のゲートにウォレットは不要です。公開デモの有料ツールは、Base Sepolia テストネットの USDC（eip155:84532）を入金した専用のホットウォレットを使用します。分析ではメインネットのチェーンデータを読み取りますが、デモでメインネットの支払いが決済されることはありません。ブリッジがトレードに署名したり、送信したりすることはありません。

公開パッケージに関する注意： [email protected] は npm に公開されており、公開デモでは有料呼び出しのデフォルトとして Base Sepolia テストネット（eip155:84532）を使用します。Base メインネット（eip155:8453）は、別のデプロイで VERIFY402_NETWORKS を明示的に有効化する必要があり、このリリースでは有効になっていません。以前公開された 1.0.8、1.0.6、1.0.5、1.0.4 の各パッケージは変更できません。また、1.0.4 はデフォルトで Base メインネットを使用していました。これらを再公開したり、上書きしたりしないでください。

ツール

ツール	料金	回答する内容
preflight_gate	無料	「この支払いリクエストまたはトランザクションに署名すべきですか？」— 理由と checked／notChecked、有効期間の短いレシートを添えて PASS／CAUTION／BLOCK を返します
verify_arbitrage	$0.05	「この取引所間のアービトラージ機会は、今この時点で実在しますか？」
check_token_safety	$0.10	「このトークンは現実的な規模で売却できますか。また、往復取引のコストはいくらですか？」— 根拠とともに TRUST／CAUTION／AVOID を返します。コード監査ではありません
get_best_route	$0.03	「このスワップでチェーン上では実際にいくら支払うことになりますか？」— 最良のルートと、見積もり対象となったすべての取引所を返します
verify_quote_fairness	$0.05	「ブローカー／ボットからこの価格を提示されました。妥当ですか？」— fair／overpaying／too_good_to_be_true を返します
get_trade_depth	$0.05	「往復取引で利益が食いつぶされる前に、ここでどれだけの規模を取引できますか？」— 規模ごとのインパクト、往復取引コスト、取引可能量を返します

preflight_gate は最初に使うゲートです。暗号資産のトランザクションまたは x402 の支払いリクエストに署名する前に呼び出してください。sign_allowed が false の場合は、署名しないでください。requires_ack が true の場合は、その理由をオペレーターに提示してください。レシートは期限切れになります（デフォルトは 90 秒）。再利用せず、もう一度呼び出してください。

支払いインテントでは、policy.allowedResourceHosts により payment.resource 内のホストを制限します。一致するホストは PASS になり、許可されていないホストは BLOCK になります。allowedResourceHosts と expectedResource のどちらも指定されていない場合、それ以外は有効なリソースでも CAUTION resource_identity_unverified となり、resource identity が notChecked に含まれます。ブリッジはこのポリシーをサーバーに転送し、サーバーが適用します。

呼び出し側が任意で指定できる以下の 2 種類のチェックは、そのまま転送されます。

• payment.idempotencyKey と policy.obligation.settledKeys を指定すると、呼び出し側ですでに決済済みのキーが拒否されます。policy.obligation.spentUsd と grantUsd を指定すると、累積支出額が許可額を超えた場合に拒否されます。ブリッジはこの状態を永続化しません。
• policy.sellerPayoutWallets は、呼び出し側が指定する支払い先の許可リストです。一致しない場合は BLOCK になりますが、一致しても出所の証明にはならず、payee_payout_binding が追加されることもありません。
• policy.sellerPayoutManifest を指定すると、呼び出し側が固定した HTTPS オリジンから、売り手署名済みのマニフェストが 402 の外で取得されます。検証済みのマニフェストの payTo リストが一致した場合に限り、payee_payout_binding が追加されます。レスポンスには、ソース、オリジン、署名者、有効期限、マニフェストのハッシュを含む payeeBinding が含まれます。

このレイヤーでのゲートの判定は助言にとどまります。ブリッジはエージェントのトランザクションキーを保持せず、判定を無視するエージェントを止めることはできません。適用の責任は署名を行うエグゼキューターにあります。レシートを検証してから署名してください。検証済みのレシートがない場合は署名ツールを呼び出さない、デフォルト拒否のリファレンス実装については、examples/preflight-guard.mjs を参照してください。

配布と実行

パッケージは npm で verify402-mcp として正式に公開されており、公式の Model Context Protocol Registry に登録されています。

npx で直接実行します（stdio トランスポート）。

npx -y verify402-mcp --help

グローバルにインストールすることもできます。

npm install -g verify402-mcp
verify402-mcp --help

または、ソースから実行します。

git clone https://github.com/a32116150-ctrl/verify402
cd verify402/mcp-bridge
npm ci
node index.mjs --help

---

AI エージェントとの連携（ステップバイステップ）

ステップ 1：無料モード（設定不要、ウォレット不要）

AI エージェントに無料の preflight_gate（署名前にトランザクションの calldata、支払いチャレンジ、受取人／金額、承認、ブロックの鮮度を確認します）を使わせるには、これをクライアント設定に貼り付けます。有料の check_token_safety チェックでは、見積もりに基づく売却可能性のチェックが追加されます。送金は実行せず、ハニーポットでないことを保証するものでもありません。

Claude Desktop（claude_desktop_config.json）または Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "verify402": {
      "command": "npx",
      "args": ["-y", "verify402-mcp"],
      "env": {
        "VERIFY402_URL": "https://verify402.onrender.com"
      }
    }
  }
}

ステップ 2：有料モード（ホットウォレットの設定）

5 つの詳細なオンチェーン検証チェック（verify_arbitrage、check_token_safety、get_best_route、verify_quote_fairness、get_trade_depth）を有効にするには、x402 経由で呼び出しごとに USDC を支払う専用のホットウォレットを設定します。

1. 専用のホットウォレットを作成する：
   • MetaMask、Rabby、または cast wallet new を使って新しいウォレットを作成します。
   • ⚠️ セキュリティ警告：普段使いの個人用ウォレット、コールドストレージ、または金庫は絶対に使用しないでください。
2. Base Sepolia テストネット（EIP-155:84532）でウォレットに資金を入れる：
   • USDC：ファウセットから Base Sepolia テストネットの USDC を入手します（ブリッジの料金は呼び出しごとに 0.03〜0.10 ドル相当のテストネット USDC です）。
   • ガス（Base Sepolia 上の ETH）：クライアントで必要な場合は、ガス代として少量の Base Sepolia テストネット ETH を入手します。公開デモではメインネットの資金は必要ありません。
3. MCP クライアントで環境変数を設定する：
   • EVM_PRIVATE_KEY にホットウォレットの 64 文字の秘密鍵を設定します。
   • VERIFY402_NETWORKS に eip155:84532（Base Sepolia テストネット）を設定します。
   • 安全上限 MAX_PAYMENT_USD（例："0.25"）と MAX_DAILY_USD（例："1.00"）を設定します。

有料モードの設定ブロック（Claude Desktop、Cursor、Cline、Windsurf）：

{
  "mcpServers": {
    "verify402": {
      "command": "npx",
      "args": ["-y", "verify402-mcp"],
      "env": {
        "VERIFY402_URL": "https://verify402.onrender.com",
        "EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
        "MAX_PAYMENT_USD": "0.25",
        "MAX_DAILY_USD": "1.00",
        "VERIFY402_NETWORKS": "eip155:84532",
        "VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
      }
    }
  }
}

OpenCode V2 の設定

opencode.jsonc（または ~/.config/opencode/opencode.jsonc）に記述します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "verify402": {
        "type": "local",
        "command": ["npx", "-y", "verify402-mcp"],
        "environment": {
          "VERIFY402_URL": "https://verify402.onrender.com",
          "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
          "VERIFY402_NETWORKS": "eip155:84532",
          "MAX_PAYMENT_USD": "0.25",
          "MAX_DAILY_USD": "1.00"
        }
      }
    }
  }
}

---

AI エージェントによる verify402 の使い方（プロンプト例）

設定すると、エージェントのコンテキストにツールが自動的に表示されます。直接プロンプトを入力できます。

• 事前チェックゲート（無料）：

  「このトランザクションに署名する前に、支払いリクエスト／calldata に対して preflight_gate を呼び出してください。BLOCK が返された場合は中止し、その理由を説明してください。」

• トークンの見積もりに基づく売却可能性チェック（0.10 ドル、コード監査ではありません）：

  「check_token_safety を使ってトークン 0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE を分析してください。設定済みの取引所で、現実的な規模の売却は可能ですか？往復取引コストはいくらで、結果は TRUST／CAUTION／AVOID のどれですか？送金制限を確認するには notChecked を読んでください。」

• 裁定取引の検証（0.05 ドル）：

  「verify_arbitrage を使って、現在のブロックでチェーン 1 上の WETH/USDC について、Uniswap V3 と Sushiswap の間に裁定取引の機会があるか検証してください。」

• 見積もりの妥当性監査（0.05 ドル）：

  「1,000 USDC に対して 0.35 WETH を提示されました。verify_quote_fairness を実行して、妥当な提示か、払いすぎなのかを確認してください。」

• 市場の深さと処理能力（0.05 ドル）：

  「Uniswap V3 の WETH について get_trade_depth を確認し、50,000 ドルのスワップでどの程度のスリッページと価格インパクトが生じるか調べてください。」

安全性

• ブリッジが署名するのは x402 決済のみです。取引への署名や送信は行いません。
• 有料ツール呼び出しごとに crypto.randomUUID() で冪等性キーを1つ生成し、x-idempotency-key として送信します。タイムアウトや応答の消失時には同じキーで再試行するため、サーバーは二重請求せず、確定済みの判定を再送します（recovery.replayed: true）。402 または409は自動で再試行されず、エラーはMCPクライアントに通知されます。このキーは秘密情報であり、ログに記録されたり返却されたりすることはありません。
• 署名の前に、有料クライアントは、402が設定済みのサーバーから既知の有料ルートに対して送られたこと、許可リストに登録されたEVMネットワーク上であること、送金先がverify402の受取先であることを必須とします。認識済みのデフォルト資産（USDC）のみ受け入れ、金額を MAX_PAYMENT_USD 以下に制限し、リダイレクトは拒否します。
• クライアントが選択したオプションだけではなく、402チャレンジ全体を検証します。提示されたすべての要件について、許可リストに登録されたネットワーク、設定済みの受取先、そのネットワークの正規USDCコントラクトおよび正規EIP-712ドメイン、eip3009 を指定する extra.assetTransferMethod、300 以下の正の整数である maxTimeoutSeconds、上限内の金額を必須とします。Baseメインネットも選択肢として含むチャレンジは、テストネットの選択肢だけに絞り込まず、全体を拒否します。またクライアントは、署名する要件がサーバーから送信されたオブジェクトと完全に同一であることを証明します。
• VERIFY402_NETWORKS、VERIFY402_PAY_TO、VERIFY402_RESOURCE_PREFIX を使って、許可リストを絞り込んだり、別のデプロイ先を指定したりできます。ブリッジのデフォルトはBase Sepoliaテストネット（eip155:84532）と、公開されているverify402の受取先です。VERIFY402_NETWORKS はサポート対象のマップ（eip155:84532、eip155:8453）に制限されます。明示的に空の値を指定すると、デフォルトにフォールバックせず、安全側に倒して失敗します。
• MAX_PAYMENT_USD は、署名が作成される前にx402クライアント内で適用されます。これを削除するとセキュリティが低下します。この上限によってブリッジが承認できる金額は制限されますが、秘密鍵が侵害された場合の保護にはなりません。
• ブリッジは X-Verify402-Client: verify402-mcp/<version> を送信し、User-Agentにも同じバージョンを含めます。これは /usage 用の匿名ラベルであり、アカウントではありません。ウォレット、キー、ユーザーIDは含まず、サーバーは自己申告で偽装可能な情報として扱います。
• preflight_gate はチェックであり、保証ではありません。notChecked を確認してください。これは受取人の評判や制裁対象のスクリーニング、コントラクトの監査、残高変動全体のシミュレーション、取引相手の監査、受取人の所有権の独立した証明、プロセスをまたぐ債務台帳の永続化、ツールの説明や応答に対するプロンプトインジェクションのスキャン、MEVへの対策は行いません。検出できるのは測定可能な署名ミスであり、あらゆる詐欺ではありません。
• 助言ではなく強制適用が必要な場合は、リファレンス実行ツールを使用してください。

依存関係と npm audit

このパッケージは、@x402/axios と @x402/evm に依存しなくなりました。x402 の支払い処理（PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE、スキーム exact、EIP-3009 認可）は、viem 上でこのパッケージに実装されています。実行時の依存関係は、MCP SDK、axios、dotenv、viem、zod 4 です。

理由：@x402 2.28.0 は zod ^3.24.2 に依存しており、これが GHSA-mrhx-c7xc-m3w5 （サイズの大きすぎる配列の検証時にメモリ枯渇を引き起こす DoS。アドバイザリの対象は zod < 4.6.6 のすべてのバージョンで、修正済みの 3.x はありません）に該当します。npm は依存関係内で宣言された overrides を無視するため、1.0.8 以前をインストールすると「重大度：高」の監査バナーが表示されていました。上流へのリクエストは x402-foundation/x402#3953 です。

現在のパッケージを tarball からインストールした場合：

$ npm i verify402-mcp
added 123 packages
$ npm audit
found 0 vulnerabilities

ブリッジは同じワイヤープロトコルで支払いを行います。動作上の変更は見た目だけです。npm ls @x402 に何も表示されず、インストールされるパッケージが 5 つ減ります。有料呼び出しのポリシー（ネットワーク許可リスト、設定済みの受取人、正規の USDC、支払いごとの上限、ツールに紐づいたリソース）に変更はなく、署名が作成される前に引き続き payment-policy.mjs で実行されます。

明示的なメインネット設定（公開デモ向けではありません）

メインネットでの決済は、ブリッジやデモのデフォルトではなく、独立したデプロイの選択肢です。サービス側のメインネット対応準備チェック、ファシリテーター、常時稼働ホスト、ウォレットへの資金補充を個別に検証するまでは、このクライアントをメインネットに接続しないでください。

# Only for a deliberate mainnet deployment, never against the public demo.
VERIFY402_NETWORKS=eip155:8453
VERIFY402_PAY_TO=<the payee named by the mainnet 402>

公開デモが提供するのは eip155:84532 です。メインネット専用のポリシーは、そのチャレンジを拒否するため、メインネットの資金が暗黙に使われることはありません。逆も同様に適用され、デモのポリシーはメインネット専用のチャレンジを拒否します。

開発

npm pack --dry-run

ライセンス

Apache License 2.0。LICENSE と NOTICE を参照してください。

このパッケージは、商用のエージェントシステムやボットを含め、使用、変更、配布できます。再配布する場合、またはこのパッケージを含む製品を配布する場合は、著作権表示、ライセンステキスト、NOTICE ファイルを保持してください。verify402 という名前とロゴは、推奨を示す目的での使用を許諾されていません。