Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】Check an x402 Endpoint Before You Pay: One Call, Real 402 Responses

2026年10月14日に「Dev.to」が公開したITニュース「Check an x402 Endpoint Before You Pay: One Call, Real 402 Responses」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

支払い要求型Webサービス(x402エンドポイント)への支払い前に、その稼働状況、要求内容、前回からの変更点を0.01 USDCで確認できるサービス。無駄な支払いを防ぎ、効率的なシステム連携を支援する。

ITニュース解説

新しいインターネットの技術では、特定の情報やサービスにアクセスするために「支払い」が必要な場合があります。これをHTTPステータスコードで表現すると「402 Payment Required」となり、これは「支払いをしないとアクセスできない」という意味を持つ特別なコードだ。しかし、この402を返すウェブサービス(「x402エンドポイント」と呼ぶこともある)の中には、たとえ支払いをしても実際にはサービスが提供されない、あるいは支払い条件が頻繁に変わってしまう、といった問題を持つものがある。システムエンジニアがそのようなサービスをアプリケーションに組み込む際、無駄な支払いをしてしまったり、予期せぬエラーに直面したりするリスクがある。

今回紹介するサービスは、そのような「x402エンドポイント」を事前に安全に「チェック」するための画期的なツールだ。その名も「GET /check?url=<target>」。これは、システムエンジニアが特定のURLに対して支払いを行う前に、そのURLが本当に生きていて、どのような支払い条件を提示しているのか、そして以前にチェックした時と比べて何か変更があったのか、という3つの重要な質問に1回の呼び出しで答えてくれる。これにより、開発者は安心して外部サービスとの連携を進められるようになる。

このチェックサービスを利用するための方法は非常にシンプルだ。例えば、コマンドラインツールであるcurlを使って、「curl -i "https://x402-catalog-history.ai-business-surface.workers.dev/check?url=https://example.com"」のように、チェックしたいターゲットのURLを指定して呼び出す。この最初の呼び出しでは、まだ支払いを行っていないため、サービスはHTTPステータスコード「402 Payment Required」を返す。これは「この情報を得るためには支払いが必要ですよ」というメッセージだ。

この402レスポンスには、支払いに関する詳細な情報が含まれている。具体的には、HTTPヘッダーの「PAYMENT-REQUIRED」と、レスポンスボディのJSON形式のデータに、支払い条件が記述されている。この情報こそが、私たちが安全に支払いを進めるために必要な「契約書」のようなものだ。

レスポンスボディのJSONデータを見てみよう。ここにはx402Version、error、acceptsといった項目がある。特に重要なのはacceptsの部分で、ここには支払いスキーム(方法)、必要なネットワーク(ブロックチェーンの指定)、maxAmountRequired(最大要求額)、支払い先のアドレス(payTo)、そして支払いのタイムアウト時間などが示されている。例えば、maxAmountRequiredが"10000"とあり、これはUSDCという暗号資産の「アトミック単位」で表現されている。USDCは通常6桁の小数点を持つため、"10000"は0.01 USDCに相当する。このように、支払いの正確な金額と単位を理解することが重要だ。

また、PAYMENT-REQUIREDヘッダーに格納されているデータは、Base64という形式でエンコードされたJSONデータだ。これをデコードすると、先ほどのJSONボディとは少し異なる「v2」形式の支払い条件が表示される。v1とv2では、例えばブロックチェーンネットワークの指定方法(v1ではbase、v2ではeip155:8453)や、使用する暗号資産の詳細(v2ではassetフィールド)に違いがある。クライアントアプリケーションがこれらの異なる表記を正しく解釈できるように実装することが、互換性確保のために非常に重要となる。

これらの支払い条件を正確に把握したら、次に実際の支払いを行う。支払い後、その「署名」を含んだ特別なヘッダー(PAYMENT-SIGNATURE)を付けて、もう一度同じURLに対してリクエストを送る。すると今度は、HTTPステータスコード「200 OK」が返ってくる。これは「支払いを確認しました。リクエストされた情報を提供します」という意味だ。

この200レスポンスに含まれるJSONデータは、私たちが求めていた「ターゲットのチェック結果」の詳細そのものだ。ここには多くの有益な情報が含まれている。例えば、targetフィールドはチェックしたURLのホスト名やパスを示し、checked_atはチェックを実行した正確な日時を教えてくれる。aliveとreasonは、対象のURLが現在稼働しているか、そして稼働していない場合の理由を説明する。

さらに詳細な情報として、probeフィールドには、チェックを実行した際の技術的な詳細が含まれる。HTTPメソッド、実際に行われたリクエスト数、最終的なHTTPステータスコード、応答にかかった時間(レイテンシ)、もしリダイレクトされた場合の最終URL、そしてコンテンツタイプなど、多岐にわたる情報が提供される。これは、対象のエンドポイントの動作状況を詳しく分析する上で非常に役立つ。

payment_challengeフィールドには、最初の402レスポンスで示された支払い条件が、より人間が読みやすい形式で再提示されている。例えば、amount_usdとしてUSD換算での金額が示されたり、asset_symbolとして暗号資産のシンボル(例: USDC)が明確に表示されたりする。これにより、支払い条件の確認が容易になる。

そして、このサービスの特にユニークな機能がhistoryフィールドだ。ここには、対象URLの過去のチェック履歴が格納されている。stored_checksはこれまでに何回チェックされたか、first_checked_atとprevious_checked_atは最初と前回のチェック日時、uptimeはそのサービスの稼働率、そして最も重要なのがchanges_since_previousだ。これは、前回のチェック以降に支払い条件やその他の重要な情報に変更があった場合に、その変更内容を具体的に教えてくれる。これにより、開発者は常に最新の支払い条件を把握し、古い情報に基づいて誤った支払いをしてしまうリスクを避けることができる。

また、delivery_evidenceフィールドは、このサービスが実際に支払いを伴う情報提供を行った証拠を示している。

この「GET /check」サービスは、システムエンジニアにとって非常に価値のあるツールだ。第一に、支払いを行う前に、目的のx402エンドポイントが本当に動作しているか、または到達不可能になっていないかを確実に確認できるため、無駄な支払いと時間の浪費を回避できる。第二に、支払いを行うべき正しいアドレスや条件が、古くなったカタログ情報ではなく、そのエンドポイント自身から直接提示されるため、常に最新で正確な支払い情報に基づいて取引を行える。第三に、同じURLを複数回チェックする場合、2回目以降の呼び出しでは差分情報(changes_since_previous)が提供されるため、変更がないかを確認するだけのポーリング処理が非常に効率的になる。

このサービスは1回あたり0.01 USDC(USDコイン)という少額で利用でき、Baseメインネット上で決済される。支払い先のアドレスは常に固定されており、設定もシンプルだ。ただし、このチェックサービス自体が内部ネットワークへのアクセス、非Webポートへのアクセス、長すぎるURL、認証情報が埋め込まれたURLなど、特定の種類のURLをチェック対象から除外するという制約がある。これらの制約に該当するURLをチェックしようとした場合は、支払いが発生する前に「400 Bad Request」として拒否されるため、安全に利用できる。

最終的に、このサービスは、支払いが必要なウェブサービス(x402エンドポイント)と安全かつ効率的に連携するための強力な基盤をシステムエンジニアに提供するものと言えるだろう。無駄な支払いを防ぎ、常に最新の情報に基づいて開発を進める上で、欠かせないツールとなるだろう。

関連コンテンツ

関連IT用語