x402 Doctor

x402 Doctor

· ライブステータス

資金をチャージしたウォレットがなくても、x402 支払い対応エンドポイントの決済フローが機能しない原因を診断します。

URL を貼り付ける（ウェブアプリ）か、x402-doctor <url> を実行する（CLI、CI）と、どのチェックに失敗したのか、その理由、修正方法が正確にわかります。すべてのチェックは、 PlainText と Ichimoku Signal のリリース時に実際に遭遇したバグに基づいています。

▶ 70 秒の紹介動画を見る（音声と字幕付き）： 機能しないエンドポイントの診断、エージェント向けの支払い前チェック、毎日の Trust Index を紹介します。

▶ 新機能：70 秒でわかる有料の修正方法：0.05 ドルで、Doctor が処方箋をお渡しします。各問題を修正するための、使用スタックに合わせた正確なコードを、ブラウザー上またはエージェント向けの JSON 形式で提供します。

チェック項目

グループ	チェック	検出内容
402 チャレンジ	returns-402	GET または POST で 402 が返らない（両方を試すか、--method を指定）
	protocol-version、challenge-header	v1 と v2 の違い、x402Version の欠落、チャレンジが誤ったヘッダーにある、ヘッダーをデコードできない
	envelope-body-mirror	ヘッダーのみのチャレンジ（@x402/express は {} を送信）、ヘッダーとボディの不一致
MCP（ツール呼び出しごとの支払い）	mcp-server	URL が 402 を返さずに MCP として応答する場合（Streamable HTTP、JSON または SSE、セッションの有無を問わず）：支払いなしで initialize と tools/list を実行
	mcp-paid-tools	有料であることを示すツールの説明がない（x402、USDC、価格など）ため、エージェントが判別できない
	mcp-payment-required	有料に見えるツールごとに、支払いなしの tools/call を 1 回実行（最大 2 件。明示的に有料のツールを優先 — タイトルに「Paid …」または価格／「via x402」があるもの。無料と自称するツール、破壊的なツール、明示的に有料でない書き込みツールは対象外）。無料で応答した場合、明示的に有料のツールに限り警告し、それ以外は情報として通知します。ツール結果に isError: true を付けて x402 の支払い要件を返す（@x402/mcp の場合）、または代わりに PAYMENT-REQUIRED を伴う HTTP 402 を返す（HTTP 経由で支払い可能だが、@x402/mcp クライアントでは不可）、JSON-RPC エラー、無料で応答するツール、または支払い手順の前に拒否される引数の例を検出します（有効な呼び出しを _meta.examples として 1 件公開すれば回避できます）。この要件には、以下の支払いオプション、決済、ウォレットのチェックも適用されます
	mcp-tool-poisoning	ツールの説明に隠された、エージェントへの指示（ツールポイズニング）：隠し Unicode 文字、<IMPORTANT> ブロック、~/.ssh または .env の読み取り、「ユーザーに伝えない」、最大額の USDC を送信する指示（コードのルール）、続いてツールごとの TypeSafe Jev（TYPESAFE_API_KEY が必要）。確実な検出結果は warn、確証がない場合は info です。公式 MCP レジストリの 96 サーバーにある 755 個のツールで調整済みです。誤検出はなく、作成したポイズニング済みツール 5 個はすべて検出されました
	mcp-payment-text、mcp-payment-structured	支払い要件が structuredContent のみにある（x402 MCP トランスポートでは content[0] 内の JSON テキストが必須）、またはテキストのみにある（structuredContent が推奨）
支払いオプション	accepts[i]-scheme、-network	スキームの欠落、CAIP-2 ではなく base／solana:mainnet などの旧形式の名前
	accepts[i]-payto、-asset	無効な EVM、Solana、XRPL、Algorand アドレス（XRPL と Algorand はチェックサムも確認）、USDC ではないアセット、または別のネットワークの USDC（例：Base 上の Base Sepolia USDC）。Algorand では ASA ID ではないアセット（USDC は ASA 31566704）、XRPL では drops 単位でない XRP の金額、または Ripple 以外の発行者による「RLUSD」
	accepts[i]-amount	最小単位ではなく、ドル単位の小数金額（"0.02"）、ゼロまたは整数以外の金額
	accepts[i]-extra	Solana で extra.feePayer がない（クライアントは「feePayer is required」エラーを出す）、EVM で EIP-712 の name／version がない
	accepts[i]-batch、-batch-delay、-batch-deposit、batch-escrow	batch-settlement スキーム（x402 エスクローへの入金 1 回と、呼び出しごとの署名済みバウチャーをまとめて請求）：extra.receiverAuthorizer がない（クライアントが拒否）、withdrawDelay がない、または 900 秒〜30 日の範囲外、EIP-3009 の入金に EIP-712 ドメインがない、minDeposit が最小単位でない、ネットワーク上にエスクローがデプロイされていない。購入者が確約する入金額と出金遅延
リソース	resource-url	https:// エンドポイントでの http:// リソース URL（TLS プロキシの背後にある Express で trust proxy が設定されていない場合）
	resource-metadata	説明／mimeType の欠落
決済	solana-payout-account	アセットのトークンアカウントを持たない Solana の受取ウォレット：すべての決済がオンチェーンで失敗します
	xrpl-payout-account、xrpl-payout-trustline	有効化されていない、Deposit Authorization がオンになっている、またはオプションで指定されていない宛先タグを必要とする XRPL の受取アカウント。RLUSD などのトークンでは、発行者へのトラストラインがない（または凍結されている）：すべての支払いが失敗します
	accepts[i]-lightning、lightning-invoice、lightning-request-hash	Bitcoin Lightning（x402 の exact、lnbtc、2026 年 9 月）：payTo はノードキーである必要があり、金額はミリサトシ単位、paymentFlow: "upfront" とリクエストのバインディング（http:1／mcp:1）が必要です。extra.invoice の BOLT11 インボイスをデコードし、オプションと完全に一致する必要があります（金額、bc／tb、maxTimeoutSeconds と一致する有効期限、payTo による署名、有効期限内）。さらに extra.requestHash を含める必要があります。http:1 の場合、このハッシュはチェッカー自身のリクエストに基づいて再計算されます
	algorand-payout-optin	アセットにオプトインしていない Algorand の受取アドレス（アカウントはオプトイン後にのみ ASA を受け取れます）：すべての支払いが失敗します
	solana-wallets	PayAI による Solana の決済で Phantom が拒否される（送金前に Lighthouse の指示があるため）
支払い可能なユーザー	wallets	ウォレットごと（MetaMask、Coinbase Wallet、Rabby、Phantom、Solflare、Backpack、Pera、Defly、Xaman、Crossmark、GemWallet、x402 エージェント）に、支払いが機能するネットワークと失敗するネットワーク、およびその理由を表示します。JSON レポートでも wallets として出力されます
	metamask-site-scan	METAMASK_SCAN=on の場合のみ（デフォルトでは無効：エンドポイントに公開 API もライセンスもありません）。MetaMask のサイトスキャナー（Blockaid）がドメインをブロックしている（例：「wallet drainer」）：MetaMask ユーザーはサイトを開いたり、ブラウザーで支払ったりできません。誤検出の報告方法も表示します。エージェントには影響しません
	evm-payto-eoa	EVM の受取ウォレットが通常のウォレット（EOA）：MetaMask の Blockaid チェックで、支払い署名が「欺瞞的なリクエスト」と判定される場合があります。情報として通知し、解除の申請方法も表示します
検出	bazaar、bazaar-output	Bazaar 宣言の欠落または無効、出力例がスキーマと一致しない
	market-price	x402 Trust Index における、他の販売者の比較可能な有料 API と比べた価格の位置（中央値と範囲。TypeSafe Jev が比較可能と判断したもの。TYPESAFE_API_KEY が必要）。常に info です。エージェントの事前チェックでより安価なサービスが推奨される場合、または他と比べて大幅に安い料金を設定している場合にヒントを表示します
	bazaar-replay	宣言されたリクエスト例が 402 を返さず、Bazaar がインデックスに登録できない
	openapi-present、openapi-title、openapi-guidance	/openapi.json、info.title、info.x-guidance の欠落
	well-known	/.well-known/x402 の欠落（情報として通知）、読み取り不可（URL のリソースも、url を持つオブジェクトも読み取ります）、またはチェック対象とは別のホストのリソースが列挙されている（リクエストの Host ヘッダーから構築され、クローラーに古いドメインを示し続けます）。自身のドメインを指す *.onrender.com などのプラットフォームアドレスは問題ありません
	bazaar-listing	CDP Bazaar でこのルートがどこに掲載されているか（同じパス、同じ payTo）：このオリジンの下、未掲載、または別のホストの下のみ。Bazaar は支払い者が使用した URL を保持するため、ドメイン移行後も、誰かが新しいドメイン経由で支払うまでは、ルートは古いホストのまま掲載されます。ウェブチェックと有料 API で確認します（CLI は対象外）
	merchant	GoPlausible のカタログで販売者に表示される x402-merchant 拡張（名前、ウェブサイト、ロゴ、カテゴリ）：形式が正しくない場合は警告し、Algorand を提供するエンドポイントで欠落している場合は情報として通知します
ブラウザー	paywall	メインネットのエンドポイントで、テストネットモードのブラウザーペイウォールが設定されている（@x402/paywall はデフォルトでテストネットを使用します。フラグは JS または JSON の設定から読み取ります）
ステータス：pass、warn（動作しますが、何か問題があります）、fail（支払いに失敗する、または有効な x402 ではありません）、info。

Web アプリ

npm install
npm start          # http://localhost:3001

レポートは共有できます：https://<host>/?url=<endpoint>&method=GET を開くと、ページの読み込み時に診断を実行します。

API：POST /api/diagnose に { "url": "...", "method": "GET" | "POST" } を指定すると（method は省略可能）、{ url, method, overall, checks[], challenge, share_url } が返されます。share_url は上記のページへのリンクで、イシューやチャットに貼り付けられます。IP アドレスごとに毎分 10 件まで診断できます。

エージェント向け有料 API（x402）

GET /api/v1/diagnose?url=<endpoint>&method=GET|POST は同じレポートを返します。x402 経由で Base または Solana 上で 1 回あたり $0.01 USDC です。レート制限はありません。エージェントと CI パイプライン向けであり、Web ページは引き続き無料です。

• 未払いのリクエストには、Bazaar の入力スキーマと出力スキーマを含む x402 チャレンジ（PAYMENT-REQUIRED ヘッダーと、本文内の同内容）が返されます。
• 無効な入力（不正な URL、非 http(s)、不明な method）は支払い前に 400 が返されます。url を指定しない場合、ルートは 402 を返すため、x402scan などのインデクサーが登録できます。url なしで支払うと 400 が返されます。
• x402 ミドルウェアは 2xx のレスポンスが返された後にのみ決済するため、診断がエラーになった場合、料金は請求されません。
• 検出：/openapi.json（x-payment-info を含む）および /.well-known/x402。
• ブラウザーでルートを開くと、402 のみが返される代わりに、ウォレットのペイウォール（まず Base：MetaMask、Coinbase Wallet）が表示されます。
• Bazaar：ファシリテーターは、ルートに対する最初の決済が完了した後、そのルートを一覧に登録します。CDP キーを設定している場合、有料リクエストを 1 回（例：ブラウザーのペイウォールから）実行すると、エージェントが検索する CDP Bazaar にルートが登録されます。

# pay-per-call from Node with @x402/fetch
const paidFetch = wrapFetchWithPayment(fetch, client);   // client with an EVM or SVM signer
const report = await (await paidFetch("https://<host>/api/v1/diagnose?url=https://api.example.com/paid")).json();

購入者向けの支払い前チェック：GET /api/v1/preflight

GET /api/v1/preflight?url=<endpoint>&max_usd=0.05&network=<caip2>&method=GET|POST、1 回の呼び出しにつき $0.001 USDC： これまで利用したことのない x402 エンドポイントにエージェントが支払う前に呼び出してください。エンドポイントに支払うことはありません。

{
  "verdict": "go",                     // go | caution | no_go
  "safe_to_pay": true,
  "summary": "OK to pay: $0.02 on Solana.",
  "recommended_option": 1,             // index into the endpoint's accepts[]
  "options": [{ "network": "eip155:8453", "asset_symbol": "USDC", "usd": 0.02, "payable": true, "problems": [] }, …],
  "signals": { "https": true, "advertised_price_usd": 0.02, "listed_in_cdp_bazaar": true },
  "reasons": [],                       // [{ level: no_go | caution | info, code, message }]
  "cached": false
}

判定	条件
no_go	402 が返されない、または有効なチャレンジがない。どのオプションも決済できない（payTo／金額が不正、fee payer または EIP-712 ドメインがない、Solana の支払い先ウォレットにトークンアカウントがない）。最安のオプションが max_usd を超える。指定された network で支払い可能なオプションがない
caution	OpenAPI で公表されている金額より高い。HTTPS ではない。既知の USDC コントラクトではない。金額が小数。リソース URL が指定された URL と異なる。テストネットのみ。誘い文句（下記）。同等のサービスより 20 倍以上高い（下記）
go	上記のいずれにも該当しません。recommended_option は、支払い可能な USDC オプションのうち最安のものです（network が指定されている場合はそのネットワーク上のもの）

誘い文句のチェック（TYPESAFE_API_KEY が設定されている場合の TypeSafe の Jev）：支払い可能なエンドポイントについて、プロトコルのチェックでは判定できないことを Jev が判断します。そのドメインを所有していないブランドの公式サービスを装っていないか（brand_impersonation）、無料トークン、エアドロップ、または確実なリターンで誘っていないか（lure_description）、宣言された出力では実現しないことを約束していないか（output_mismatch）を確認します。明確に「はい」と判定された場合は caution、判断が分かれる場合は info です。no_go への変更や、go への変更は決して行いません。確率は signals.jev_lure に含まれます。CDP Bazaar の実在する掲載情報 300 件では、ブランドや誘い文句の表現を理由に caution が付くことはありませんでした。

価格チェック（同じキーを使用）：同等のサービスと比べて価格が大幅に高くないかを確認します。Doctor は x402 Trust Index から他の販売者の有料 API を最大 24 件取得します。対象 API の説明文と珍しい単語が共通するものが選ばれ（販売者あたり最大 2 件）、各候補について Jev が、購入者にとって同程度に役立つかを判断します。同等のサービスが 5 件以上ある場合、その価格の中央値を比較対象とします。5 倍以上（かつ $0.05 以上高い）なら info、20 倍以上（かつ $0.25 以上高い）なら caution となり、どちらも price_high を付与し、より安価な代替案を最大 3 件まで提示します。比較結果は signals.price_check（comparable_median_usd、comparables、ratio、cheaper[]）に含まれます。価格は販売者が決めるものであり、価値があるかどうかはエージェントが判断するため、価格チェックによって no_go になることはありません。

CDP Bazaar に掲載されていない場合は、info のみが報告されます。結果は URL、予算、ネットワークごとに 10 分間キャッシュされるため（cached: true）、支払いのたびにチェックしても高速です。

複数のエンドポイントを一度に：GET /api/v1/preflight/batch

GET /api/v1/preflight/batch?url=<a>&url=<b>&max_usd=0.05、最大 10 件のエンドポイントにつき1 回の呼び出しで $0.005 USDC（各エンドポイントに url パラメーターを 1 つ指定。重複は 1 件として数えます）。複数のサービスを比較検討するマーケットプレイス、ディレクトリ、エージェント向けです。各エンドポイントには単独の preflight と同じ判定が行われます。エラーになるか、20 秒以内に応答しないエンドポイントは unknown となり、ほかの処理を妨げません。

{
  "count": 2,
  "counts": { "go": 1, "caution": 0, "no_go": 1, "unknown": 0 },
  "results": [
    { "url": "https://a.example/paid", "verdict": "go", "safe_to_pay": true, "summary": "OK to pay: $0.02 on Base.", "recommended_option": 0, "options": […], "reasons": [] },
    { "url": "https://b.example/paid", "verdict": "no_go", "safe_to_pay": false, "summary": "Do not pay: …", … }
  ]
}

高額な呼び出しの前に：GET /api/v1/preflight/deep

GET /api/v1/preflight/deep?url=<endpoint>&max_usd=0.5、1 回の呼び出しにつき $0.01 USDC：preflight の全回答に加え、以下を返します。

• diagnosis：診断の全内容（overall、各チェック、および問題または警告がある項目を problems として表示）。
• history：過去 30 日間の日次スキャン結果。1 日につき { date, status } を 1 件返します。
• seller：同じオリジンにある、販売者のほかのスキャン済みエンドポイント（件数、本日時点で支払い可能な件数、支払い可能率の平均、信頼性に問題があった件数）。エンドポイントがスキャンの半分未満でしか支払い可能でなかった販売者の場合、go は caution に変わります（unreliable_seller）。
• domain：ドメイン移転のチェック（well-known、bazaar-listing）。たとえば、古いドメインにのみ Bazaar の掲載情報がある場合などです。

支払い済みで配信済み？ GET /api/v1/delivery-check

GET /api/v1/delivery-check?url=<endpoint>&method=GET|POST、チェックごとに $0.25 USDC：x402 Doctor がエンドポイントの 販売者自身が掲載情報で宣言したサンプル入力を使って一度購入し、返された内容を公開します。エンドポイントが配信されることを 証明したい販売者や、大口注文の前に確認したい購入者向けです。

• 支払う前にチェック：エンドポイントは https である必要があり、fizzl.eu のルートではなく、支払い前チェックで go が返され、 Base 上の USDC で支払い可能で、料金が最大 $0.10 である必要があります。それ以外の場合は 400（または当日のチェック上限である 20 件に達している場合は 503）が返され、料金は一切請求されません。
• 回答が先に届き、購入はその後すぐに行われます：有料呼び出しはジョブの id と status_url を返します。 delivery-check.yml が 10 分ごとにキュー（GET /api/v1/delivery-check/queue、 無料）を取得し、専用のスポット購入ウォレット（SPOT_BUY_KEY。サーバーにウォレットキーはありません）で購入します。 支払いが決済されたジョブだけがキューに公開されます。
• スポット購入と同じ手順（lib/spot-buy.js）：支払い直前に OFAC の支払い先チェックを含む新たな事前チェックを行い、 販売者が宣言したサンプル入力を使用し、回答を宣言された出力スキーマに照らしてチェックし、オンチェーンで請求額を測定します。
• 公開結果：GET /api/v1/delivery-check/<id>（無料）では、最初に queued が表示され、その後、結果 （delivered、off_schema、empty、charged_not_delivered、payment_rejected、error_not_charged、または支払い前に 停止したステップ）とトランザクションを含む done が表示されます。すべての結果は delivery-data ブランチにあります。

ジョブはクレジット用 Redis（CREDITS_REDIS_URL）に保存されます。これがない場合、支払い前にルートから 503 が返されます。

プリペイドクレジット：GET /api/v1/credits/1000

頻繁にチェックするエージェントは、前払いできます。x402 で 1000 クレジットを $0.80、または 10,000 クレジットを $7.00 （20% と 30% 割引）で購入でき、有効期間は 1 年です。1 クレジットは $0.001 です。事前チェックは 1、バッチは 5、詳細な事前チェックまたは 診断は 10、修正は 50 クレジットかかります。パックの応答には credit_key が含まれます。有料呼び出しでは、支払いの代わりにこれを x-credit-key ヘッダーとして送信してください。GET /api/v1/credits（無料）では料金が表示され、ヘッダーを付けると残高も表示されます。 呼び出しが失敗した場合、クレジットは返還されます。キーがない場合やクレジットが不足している場合は、通常どおり 402 が適用されます。 CREDITS_REDIS_URL（Upstash などの永続 Redis）が必要です。presign-guard インスタンスを使用できます。キーは分離されています。これがない場合、 パックは販売されません。

コードとしての修正：GET /api/v1/fix

GET /api/v1/fix?url=<endpoint>&method=GET|POST&stack=<optional>、呼び出しごとに $0.05 USDC：エンドポイントを診断し、 失敗したチェックまたは警告があるチェックごとに、スタックに合わせてコード化し、独自の値（payTo、amount、network、route）を埋め込んだ 具体的な修正方法を返します。

{
  "stack": { "id": "express", "name": "Express (@x402/express)", "detected_from": "x-powered-by: Express" },
  "summary": "3 fixes (1 blocking), for Express (@x402/express).",
  "fixes": [
    {
      "recipe": "amount",
      "severity": "warn",
      "checks": ["accepts[0]-amount"],
      "title": "Amount \"0.01\" → \"10000\" ($0.01)",
      "why": "x402 amounts are integer strings in the token's smallest unit; USDC has 6 decimals.",
      "steps": ["Easiest: let the SDK convert it by using price: \"$0.01\" instead of an amount."],
      "code": [{ "language": "javascript", "stack": "node", "label": "Route config", "snippet": "accepts: [{ scheme: \"exact\", price: \"$0.01\", ... }]" }],
      "verify": "Run x402 Doctor again on https://…; accepts[0]-amount should pass."
    }
  ],
  "unfixed": []
}

スタックは応答ヘッダー（x-powered-by、server、Vercel／Render／Cloudflare のヘッダー）とチャレンジから読み取られます。 express、next、hono、node（別のフレームワークの背後で動作する @x402 SDK）、python、または generic（あらゆる言語の 生 HTTP）を指定できます。推測が間違っている場合は stack= を渡してください。Node のスニペットは @x402 v2 のルート設定を使用します。 これは @x402/express、/next、/hono で共通です。Express のみに適用される行には、その旨が記載されています。

レシピ（lib/recipes.js、それぞれ test/recipes.test.js にテストが 1 件あります）：402 がまったく返されない（ペイウォール前の 200、 先に認証または検証が行われる、404／405、到達不能）、v1 または無効なチャレンジ、ヘッダー名の誤り、ボディミラーなし、accepts なし、 scheme、旧式のネットワーク名、無効な payTo（引用符、スペース、誤ったチェーンを検出）、USDC アセット、10 進数の金額、Solana の 手数料支払者、EIP-712 ドメイン、プロキシ背後の http リソース URL、リソース URL とメタデータ、Bazaar の宣言とサンプル、Solana の 支払い先トークンアカウント、PayAI 上の Phantom、メインネット上のテストネット用ペイウォール、openapi.json。レシピがないものは、 診断のヒントとともに unfixed の下に返されます。

結果からの学習：POST /api/v1/outcome

有料の事前チェック後、購入者はエンドポイントへの支払いを実行した際の結果（paid_ok、再度402となったpaid_failed、またはpaid_error）を無料で報告できます。x402-safe-fetchでは、shareOutcomes: trueを指定すると報告できます。

{ "outcome": "paid_failed", "status": 402, "preflight": { …the signed preflight answer… }, "query": { "url": "…", "method": "GET", "max_usd": "0.05", "network": "eip155:8453" } }

• 報告がカウントされるのは、Doctorがそのクエリについて署名した実際の事前チェックがあり、各事前チェックにつき1回（receipt.request_id）の場合のみです。そのため、虚偽の報告には有料の事前チェックが必要になります。
• Doctorは、30日間にわたってエンドポイントごとに報告を集計します。報告された支払いの大半が失敗し、支払い元のウォレットが3つ以上異なる場合、後続の事前チェックにpayments_fail_after_preflight（注意）が追加されます。件数はsignals.agent_outcomesに表示されます。
• 報告は利用ログに記録されます（エンドポイント、結果、ステータス、判定、レシートの支払者）。購入者に関するその他の情報は記録されません。

署名付き判定

有料の回答（diagnose、preflight、batch、deep、fix。HTTPとMCPの両方）には、Doctorが署名したreceiptが含まれます。そのため、エージェントは後からどのエンドポイントについてどの判定を受け取ったかを証明できます。たとえば、なぜ支払ったか、または支払わなかったかを証明できます。

"receipt": {
  "request_id": "…", "route": "GET /api/v1/preflight", "input_sha256": "…",
  "payment": { "network": "eip155:8453", "amount": "1000", "payer": "0x…", "nonce": "0x…", "proof": "eip3009" },
  "signed_at": "2026-09-27T08:00:00.000Z", "signer": "0x…",
  "algorithm": "eip191-canonical-json-v1", "signature": "0x…"
}

• 署名対象： receipt.signatureを除いた回答全体を、正規化されたJSONとして（プロファイルjs-json-stringify-sorted-utf16-ascii-v1：キーはUTF-16コード単位でソートし、空白を詰め、U+007F以上のすべてのコード単位を小文字の\uXXXXとして表記し、数値はJavaScriptのJSON.stringifyによる表記にします（1.0 → 1、0.000001 → 0.000001）。その後、UTF-8バイト列に変換します。Pythonのjson.dumpsが一致するのはASCIIキーと整数の場合のみなので、examples/canonical.pyを使用してください。このファイルにはverify_receipt(answer)もあります）、EIP-191のpersonal_signで署名します。判定を変更したり、別のリクエストに移したりすると、検証に失敗します。
• payment： この回答の購入に使われた支払い情報で、x402の支払いペイロードから取得されます。Baseでは、支払者とEIP-3009のnonceが含まれるため、誰でもUSDCコントラクトのAuthorizationUsed(payer, nonce)イベントからオンチェーンの決済を確認できます。Solanaでは、支払者と送信した署名済みトランザクションのSHA-256が含まれます。
• input_sha256： {"route", "input"}の正規化されたJSONのSHA-256です。inputは、クエリパラメーター（HTTP）またはツールの引数（MCP、ルートはmcp <tool>）を文字列として表します。
• 署名者： /.well-known/x402-doctor-signer.jsonに記載されています。退役した署名者も記載されているため、過去のレシートも引き続き検証できます。
• 無料の検証： POST /api/v1/verifyに{"response": …, "route": …, "input": …}を渡すと、valid、signer、known_signer、input_matchesが返されます。

クライアントを更新せずにキーをローテーション： 支払い用ウォレット（0x6B0F4651eD42893ab58139938175E4a69f175F25）は、fizzl receipt signer / service: x402-doctor / signer: <address> / valid_from: <YYYY-MM-DD>に対するpersonal_signを使って各署名キーを認証します。これをRECEIPT_SIGNER_CERT（YYYY-MM-DD:0x<signature>。ウォレットのブラウザーで/sign-receipt-keyを使って生成）として設定してください。起動時に検証され、各レシートにreceipt.certとして含まれるため、支払い用ウォレットのみをピン留めしたクライアントでも、新しいキーをオフラインで検証できます。

presign-guardと同じ形式なので、1つの検証ツールで両方に対応できます。キーはRECEIPT_SIGNER_SECRETから取得されます（資金は保有しません）。これを設定しない場合、回答には署名されません。

x402 Trust Index

1日に1回、trust-scan.ymlが、CDP Bazaar、MPPディレクトリ、およびGoPlausibleファシリテーターの検出リスト（Algorand上のx402。Bazaarに掲載されていない約2,500のエンドポイント）に含まれるすべてのリソースに対して、支払い前チェックを実行します（読み取り専用：402チャレンジで停止し、ホストあたり同時リクエストは最大2件、オリジンあたり/openapi.jsonは1件、/trustへのリンクを含むUser-Agentを使用）。結果は、リソースごとの30日間の履歴にまとめられ、1日につき1文字（g＝進行可、c＝注意、n＝不可、x＝到達不可、-＝未スキャン）として、trust-dataブランチのindex.jsonとsummary.jsonに公開されます。

• 事前決済チェックでは、スキャンした日が3日以上あり、その半分未満の日しか売り手が決済可能でなかった場合に、signals.track_record と caution（unreliable_history）が追加されます。
• スポット購入のサンプル： 「go」は支払い済みかつ配信済みを意味しますか？ スキャンで読み取るのは402チャレンジのみです。週に1度、spot-buy.yml が「go」のエンドポイントから少数のランダムなサンプルを購入します（lib/spot-buy.js）。対象はBase上のUSDCによるx402 exact のみで、1ホストにつき1エンドポイントとし、fizzl.euとテスト用ホストは対象外です。リクエストには、売り手が自ら宣言したサンプルを使用します（ペイウォールに到達した場合）。支払いの直前に、OFACの支払い先スクリーニングを含む新たな事前チェックを行い、上限を厳格に設定します（デフォルトはエンドポイント30件、1回あたり$0.05、1回の実行あたり$2。最大で50件、$0.10、$5）。ウォレットから資金が出たかどうかはオンチェーンで測定し（前後のUSDC残高を比較）、売り手のPAYMENT-RESPONSEをオンチェーンの記録と照合します。各結果はdelivered、off_schema（宣言された出力スキーマに一致しない応答）、empty、charged_not_delivered、payment_rejected、error_not_charged、payment_failedのいずれかです。実行結果はspot-dataブランチ（latest.json、results/<date>.json）に追記されます。支払いにはシークレットSPOT_BUY_KEYのみを使用し、数USDCを保有する専用ウォレットを使います。このキーがなければ、すべての実行は支払いを行わないドライランです。最新の実行結果は/trust（「支払い済みかつ配信済み？」）とGET /api/trust/spot（概要と各購入結果。ウォレットの詳細は含みません）で確認できます。GET /api/trust?url=…では、そのエンドポイントが購入対象になっていた場合にspot_buyが追加されます（lib/spot-results.js）。支払いを伴う事前チェックでは、同じ情報がsignals.spot_buyとして追加されます。また、エンドポイントが自らの掲載情報で宣言したサンプルリクエストに対して支払いを受け取り、エラーを返した場合はcaution（charged_without_answer）が追加されます。同じウォレットは、手動で開始する別の支払いにも使われます。CDP Bazaarでは、ルートはその支払いが確定してから掲載されるため、index-payment.ymlが、当社のfizzl.euのルートの1つに対して最大$0.01の呼び出しを1回支払います（scripts/index-payment.js）。これは何も公開しないため、サンプルには引き続き他の売り手のみが含まれます。
• 制裁リストの照合。 各支払い先アドレス（x402のpayTo、MPPのrecipient）を、presign-guardが無料で公開している米国財務省のリストに含まれるOFAC SDNリストのデジタル通貨アドレスと照合します（lib/sanctions.js。6時間ごとに更新）。アドレスが掲載されている場合、SDNの項目とともに、事前決済チェック（payto_sanctioned）、支払いを伴うチェック、毎日のスキャンでno_goになります。signals.sanctionsには、何をどの公開情報と照合したかが記録されます。summary.jsonには、掲載されたアドレスに支払うスキャン済みリソースの数（payto_sanctioned）が集計されます。リストが利用できない場合、判定は行われません（signals.sanctions.unavailable）。
• GET /api/trust?url=<resource>（無料、IPあたり30回/分）：1つのリソースの実績です。 GET /api/trust/summary：最新スキャンの合計です。/trust：検索機能とスキャンのルールを掲載した公開ページです。
• GET /api/trust/network?network=xrpl（またはxrpl:0のようなID。無料）：ネットワークを提供する、スキャン済みのすべてのx402エンドポイントを表示します。今日決済可能かどうかとその理由も確認できます（スキャンでは決済できないネットワークをunpayableとして記録し、最初に発生した問題も記録します）。売り手のサイトごとにまとめられます。/xrpl：XRP Ledger上のx402の公開ステータスページで、各支払いアカウントの台帳チェックも表示します。/algorand：Algorand上のx402について同様の情報を表示し、各支払いアカウントのUSDCオプトインも確認できます。
• サービスの重複排除と種類。 売り手は同じAPIを（コイン、都市、ティッカーごとに）何度も掲載することが多いため、エンドポイント数は市場規模を実際より大きく見せます。説明文の大部分が共通する（Jaccard係数 ≥ 0.5、lib/services.js）1つの売り手の決済可能なエンドポイントは、1つのサービスとして数えます。2026年10月9日時点で、決済可能なエンドポイント40,451件は18,475のサービスに相当し、そのうち3分の1を1つの売り手だけで掲載していました。各サービスにはカテゴリ（crypto、security、on-chain、AI、search、finance、media、places、social、developer tools、other）が付与されます。毎日のスキャン後にTypeSafe Jevが選択し（scripts/categorize.js）、説明文ごとにtrust-dataブランチのcategories.jsonにキャッシュします（1日に新たに処理するのは最大1,500件）。それまではキーワードから推定します。/api/trust/summary（services）、/api/trust/network（services、categories、売り手ごとのservices、エンドポイントごとのcategoryとsame_service_endpoints）、および/trust、/algorand、/xrplで確認できます。
• おとりの可能性。 スキャン後、支払いを伴う事前チェックで実行するのと同じおとりチェック（TypeSafe Jev：有名ブランドの公式サービスに見せかけながら、そのブランドが所有していないドメインで運営されているサービス、または無料トークン、エアドロップ、確実なリターンをうたう誘い）を、すべてのサービスに対して実施します。1日に新たに処理するのは最大1,000件で、説明文ごとにcategories.jsonにキャッシュされます。Jevが確信を持って判定した（≥ 0.85）サービスは/trustと/api/trust/summary（services.bait：チェック済み件数、フラグが付いた件数、確信度の高い上位100件）に掲載され、/api/trust/networkの各エンドポイントと/algorand、/xrplでも表示されます。
• 自分で実行する場合：node scripts/trust-scan.js --out trust-data --limit 200。

毎週の x402 ヘルスレポート

毎週月曜日、weekly-report.yml が Trust Index の過去 7 日分をレポートにまとめます。内容は、問題のない Bazaar リソース、注意事項があるもの、支払い不可のものの件数、最もよくある理由とそれぞれの修正方法、支払い可能なリソースが対応するネットワーク、そして今週の変化（問題発生、修正、不安定、新規）です。販売者やホストの名前は記載しません。レポートとその数値、X、Discord、Reddit 向けの投稿案（人が確認して投稿するためのもの）は、weekly-reports ブランチの reports/<date>.md、.json、-posts.md に出力されます。ローカルで実行する場合： node scripts/weekly-report.js --out reports [--index trust-data/index.json]。

同じ実行で、ネットワークごとのダイジェスト（Algorand と XRP Ledger）も生成します（network-digest.js）。内容は、そのネットワークで支払い可能なエンドポイントの数と販売者の数、先週からの変化（新しいエンドポイント、支払い不可になったエンドポイント、新しい販売者）、そのネットワークのみでの支払いに対応するものの数、価格の中央値、最大規模の販売者です。支払い可能な販売者の名前のみを記載し、問題は件数で示します。ファイルは reports/<date>-<network>.md と -posts.md（X およびコミュニティ向けの投稿案）、さらに来週との比較に使うスナップショット reports/networks/<network>-latest.json です。ローカルで実行する場合： node scripts/network-digest.js --out reports [--index trust-data/index.json] [--previous reports/networks]。

MCP サーバー

https://x402-doctor.fizzl.eu/mcp は、Claude、Cursor、エージェントフレームワーク向けの MCP サーバー（Streamable HTTP、ステートレス）で、公式 MCP レジストリに io.github.Fizzl13/x402-doctor として登録されています。

ツール	価格	戻り値
x402_quick_check	無料、1 時間あたり 10 回	pass/warn/fail、問題の件数と上位 3 件
x402_diagnose	x402 経由で $0.01 USDC	修正のヒントを含むすべてのチェック結果。GET /api/v1/diagnose として提供
x402_preflight	x402 経由で $0.001 USDC	エンドポイントへの支払い前の go/caution/no_go。GET /api/v1/preflight として提供
x402_preflight_batch	x402 経由で $0.005 USDC	最大 10 個のエンドポイント（urls）のプリフライト結果。GET /api/v1/preflight/batch として提供
x402_preflight_deep	x402 経由で $0.01 USDC	プリフライト結果に加え、診断、履歴、販売者およびドメインのチェック。GET /api/v1/preflight/deep として提供
x402_fix	x402 経由で $0.05 USDC	お使いのスタック向けのコード変更。GET /api/v1/fix として提供
feedback	無料	バグまたは不足している機能を報告します。POST /feedback（下記）として提供

有料ツールは、x402 MCP トランスポート（_meta["x402/payment"]）を使って MCP 呼び出し内で支払います。ネットワークは Base または Solana で、HTTP ルートと同じ価格、同じ受取ウォレットです。無効な入力は支払い前に拒否され、呼び出しが失敗しても課金されません。

フィードバック

バグを見つけた場合や、足りないものがある場合は、POST /feedback（無料、支払い不要）または MCP ツール feedback でお知らせください。

curl -X POST https://x402-doctor.fizzl.eu/feedback \
  -H 'content-type: application/json' \
  -d '{"type": "feature", "message": "Also check the facilitator /supported list", "endpoint": "/api/v1/diagnose"}'

type は bug、feature、other のいずれかです。message は必須で、最大 2000 文字です。endpoint と contact は任意です。回答は ID を含む 202 です。呼び出し元ごとに、1 時間あたり最大 10 件まで報告できます。報告は使用状況ログ（/admin/usage に表示）に記録され、すべて人が確認します。報告内容が自動的に実行されたり、何かが自動的に変更されたりすることはありません。GET /feedback でスキーマを確認できます。診断が他のサーバーの feedback ツールを呼び出すことはありません。無料とされているツールはスキップされます。

CLI

npx github:Fizzl13/x402-doctor https://api.example.com/paid
npx github:Fizzl13/x402-doctor https://api.example.com/paid --method POST --json

終了コードは、pass/warn の場合は 0、チェック失敗時（または --strict 指定時に警告がある場合）は 1、使用方法のエラー時は 2 です。 CLI は localhost を診断できるため、開発サーバーを対象に実行できます。

GitHub Action

プッシュのたびに x402 エンドポイントをチェックします。402 に問題があるとステップは失敗し、各問題は実行結果と PR にアノテーションとして表示されます。また、ジョブのサマリーには問題とその修正方法が並べて表示されます。 GitHub Marketplaceでは x402 Doctor check として公開されています。チェックに合格した公開エンドポイントには、バッジのスニペットも表示されます。

- uses: Fizzl13/x402-doctor-action@v1
  with:
    urls: |
      https://your-api.example.com/paid
      https://your-api.example.com/other

入力	デフォルト
urls	(必須)	1 行に 1 つ、またはカンマ区切りで指定します。ジョブ内で先に起動した開発サーバーでは localhost も使用できます。
method	GET を試し、次に POST	GET または POST
fail-on	fail	fail：チェックに失敗するとステップも失敗します。warn：警告でも失敗します。never：結果を報告するだけです。

出力は overall（URL 全体で最も悪い結果を示す pass、warn、fail）と report（レポート全体を JSON 形式で表示）です。Action はランナーに組み込まれた Node （GitHub ホステッドランナーの場合は 20.18 以降）を使用し、ジョブの Node バージョンは変更しません。読み取り専用のため、ウォレットも支払いも不要です。

または、通常の run: ステップで CLI を実行できます。

- run: npx -y github:Fizzl13/x402-doctor https://your-api.example.com/paid

設定

変数	用途
PORT	Web サーバーのポート（デフォルトは 3001）
SOLANA_RPC_URL	Solana の支払いアカウント確認用 RPC（デフォルトは公開 mainnet RPC。レート制限があります）
AGENT_PAYOUT_WALLET	有料 API の支払いを受け取る Base アドレス（または DOCTOR_PAYOUT_WALLET）
AGENT_PAYOUT_WALLET_SOLANA	有料 API の支払いを受け取る Solana アドレス（または DOCTOR_PAYOUT_WALLET_SOLANA）。USDC トークンアカウントが必要です
ALGORAND_PAY_TO	USDC（ASA 31566704）で有料 API の支払いを受け取る Algorand アドレス。GoPlausible のファシリテーターが決済します（ALGORAND_FACILITATOR_URL で上書きできます）。アカウントは USDC のオプトインが必要です。未設定または off の場合、Algorand オプションはありません
DOCTOR_PRICE	有料診断 1 回あたりの価格（デフォルトは $0.01）
DOCTOR_PREFLIGHT_PRICE	支払い前チェック 1 回あたりの価格（デフォルトは $0.001）
DOCTOR_BATCH_PRICE	最大 10 個のエンドポイントを対象とする、バッチ支払い前チェック 1 回あたりの価格（デフォルトは $0.005）
DOCTOR_DEEP_PRICE	詳細な支払い前チェック 1 回あたりの価格（デフォルトは $0.01）
DOCTOR_FIX_PRICE	修正 1 回あたりの価格（デフォルトは $0.05）
FACILITATOR_URL	x402 ファシリテーター（デフォルトは PayAI、https://facilitator.payai.network）
CDP_API_KEY_ID, CDP_API_KEY_SECRET	Base で Coinbase の CDP ファシリテーターを使用します（PayAI はフォールバックとして引き続き使用されます）。CDP 経由で決済された支払いでは、CDP Bazaar にルートが掲載されます
DOCTOR_SOLANA_FACILITATOR	CDP キーが設定されている場合、Solana は PayAI によって決済されます（PayAI が停止している場合は CDP が引き継ぎます）。Solana も CDP 経由で決済するには cdp を設定します
MPP_SECRET	有料ルートで x402 と併せて MPP 決済（方式 evm、Base 上の USDC、同じファシリテーター経由）を有効にします。MPP（mppx）に対応するエージェント向けです。チャレンジ ID の署名に使う、任意の長いランダム文字列を設定します。設定しない場合は x402 のみが提供されます
OUTREACH_URL / OUTREACH_KEY	任意。両方の設定が必要です。無料の Web チェックで、/openapi.json に info.contact.email を公開している壊れたエンドポイント（失敗）が見つかると、Doctor は下書きメールを OUTREACH_URL（https://wallet.fizzl.eu）の Fizzl ウォレットサーバーに渡します。認証には OUTREACH_KEY（そこに設定されているものと同じ長いランダム文字列）を使います。ウォレットサーバーは下書きのみを作成し、所有者が Telegram またはダッシュボードで送信するかどうかを決定します。Fizzl 自身のホストは除外され、各ホストにつき 1 日 1 回までです
TYPESAFE_API_KEY	任意。TypeSafe の Jev が、アウトリーチの下書きを作成する前に壊れたエンドポイントを判定します（lib/jev-triage.js）。テスト、プレビュー、トンネルサービスの場合や、有料エージェントに影響しない検出事項については、下書きを作成しません。無効または失敗時は、従来どおり下書きを作成します。テスト用だと明らかなアドレス（staging.、sandbox.、testnet、トンネル、Vercel プレビュー）と、明確な実際の問題（https 上の http リソース URL、内部または生のクラウド関数リソース URL、提示価格の 1.5 倍以上の価格、支払い可能なオプションがないこと）は、問い合わせずにコードで判定します。ANTHROPIC_API_KEY も設定されている場合、Jev が判断に迷うケースは Claude が判定します。同じキーをリポジトリシークレットとして設定すると、.github/workflows/triage.yml で Trust Index の候補すべてを手動でランク付けできます
MPP_TEMPO_RECIPIENT	MPP_SECRET と併用すると、MPP 方式 tempo も受け付けます（プッシュモード：エージェントが Tempo 上で MPP メモとともに USDC.e を送信し、トランザクションハッシュで応答します。Doctor は Tempo RPC で確認します）。Tempo で受け取るアドレスです。Tempo に対応したウォレットで、その秘密鍵を保有していることを確認してください。設定しない場合は evm のみが提供されます
MPP_TEMPO_CHAIN	4217（Tempo、デフォルト）または 42431（Moderato テストネット。pathUSD で支払います）
MPP_TEMPO_RPC	Tempo RPC を上書きします（デフォルトは https://rpc.tempo.xyz、または Moderato の RPC）

| USAGE_LOG_TOKEN | 使用量ログ専用リポジトリに対する Contents の読み書き権限を持つ、詳細な権限設定が可能な GitHub トークン。すべての呼び出しがそこに記録されます（下記参照） | | USAGE_LOG_REPO | 非公開の使用量ログリポジトリ（デフォルトは Fizzl13/usage-log） | | ADMIN_PASSWORD | /admin/usage のパスワード（ユーザー名は任意）。設定しない場合、管理ページは存在しません |

どちらの支払い先ウォレットも設定されていない場合、有料ルートは 503 を返し、アプリの残りの部分は従来どおり動作します。

使用状況ダッシュボード

/admin/usage には、Fizzl の各サービス（x402 Doctor、PlainText、Ichimoku Signal、presign-guard）へのすべての呼び出しが表示されます。 合計、収益、支払いを行ったウォレット数、サービスごとの日別呼び出し数、最も多く尋ねられた入力、入力内容、結果、支払い（Basescan／Solscan のリンク付き）を含む最新の呼び出しを確認できます。各サービスは呼び出しごとに JSON 行を 1 行、プライベートな使用状況ログリポジトリの events/<service>/<YYYY-MM-DD>.jsonl に追記します（lib/usage-log.js を各サービスにコピー）。ダッシュボードはそのログを読み取ります（lib/usage-reader.js）。402 チャレンジ、ヘルスチェック、静的ファイルは集計対象外で、入力は 300 文字で切り詰められます。ログ記録によってリクエストが遅延したり失敗したりすることはありません。

安全性

ウェブアプリは、ユーザーが送信した URL をサーバー側で取得します。

• すべての接続は、接続時にプライベートアドレスおよび予約済みアドレス（RFC 1918、ループバック、リンクローカル、クラウドメタデータ、CGNAT、IPv6 ULA／リンクローカル、あらゆる表記形式の IPv4 マップ IPv6）に該当しないか確認されるため、別途行う名前解決チェックを DNS リバインディングで回避されることはありません。リダイレクトは手動で追跡し、各ホップを再確認します。
• レスポンスの上限は 2 MB で、すべてのリクエストは 8 秒後にタイムアウトします。
• /api/diagnose（無料）は IP ごとにレート制限されます。/api/v1/diagnose は呼び出しごとに有料で、同じ保護措置を使用します。
• 診断対象のエンドポイントから取得した内容はすべてテキストとして描画され、HTML として扱われることはありません。

診断対象のエンドポイントに支払いを行うことはありません。ウォレットも署名も使わず、金銭的なリスクはゼロです。決済の検証／確定の失敗を追跡するための有料プローブ（最小額の支払いに署名して決済すること）は、意図的に対象外としています。

プロジェクト構成

server.js              Express app: /api/diagnose (free), paid API, /openapi.json, /.well-known/x402, static frontend
lib/paid-api.js        GET /api/v1/diagnose, /preflight (+ /batch, /deep) and /fix behind x402 (Base + Solana USDC)
lib/recipes.js         The fix per failed check, as code for the detected stack
lib/stack.js           Which stack runs an endpoint, from its response headers
lib/preflight.js       Pre-payment check: verdict, recommended option, reasons (cached)
lib/preflight-plus.js  Batch (up to 10 endpoints) and deep pre-payment checks
lib/bazaar-index.js    Cached CDP Bazaar index (listing signal for preflight)
lib/trust-scan.js      Trust Index scan: catalog, polite fetch, 30-day history
lib/trust-index.js     Reads the published index for preflight and /api/trust
scripts/trust-scan.js  Daily scan entry point (trust-scan.yml)
public/trust.html      /trust page
lib/media.js           Serves the explainer and paid-fix videos from their branches (/media/explainer.mp4, /media/fix.mp4)
media/explainer/       Explainer video pipeline (script, voice, recording, encoding)
lib/diagnose.js        The checks
lib/site-scan.js       MetaMask's site scanner verdict for the domain
lib/mcp-check.js       x402 over MCP: tools/list, unpaid tools/call, the payment requirement in the tool result
lib/networks.js        Known networks, USDC per network, address validation
lib/safe-fetch.js      SSRF-safe fetch (connect-time IP check, redirects, size cap, timeout)
bin/x402-doctor.js     CLI
public/index.html      Frontend
test/                  node:test suites (fixture x402 servers, SSRF, CLI, API)

テスト

npm test

テストスイートではローカルのフィクスチャサーバーに対して doctor を実行します。正常な v2 サービス（Base + Solana、Bazaar、OpenAPI、メインネットのペイウォール）と、前述の実際のバグを再現する不具合のあるサービスに加え、SSRF、サイズ上限、API、CLI のテストも実行します。