【ITニュース解説】I made an API that has no signup, because the payment is the login

従来のシステムでは、API（アプリケーション・プログラミング・インターフェース）を利用する際、まずアカウントを作成し、メールアドレスを登録し、確認メールのリンクをクリックし、ウェブサイトのダッシュボードにアクセスして利用プランを選択し、さらにAPIキーと呼ばれる認証情報を探し出してコピーし、自分のシステムの設定ファイルに貼り付ける、といった複数の手間がかかる手順が必要だった。これらの手続きは人間がブラウザを使って行うことを前提としており、自動化されたエージェントやプログラムが夜中にAPIを利用しようとした際に、もし認証情報が必要な壁にぶつかると、人間が介入できないため、そのまま処理が進まず、システムはただ「データが利用できません」と報告して次の処理に移ってしまう、という問題があった。

このような問題を解決するため、ある開発者は「サインアップ不要」な新しいAPIを開発した。このAPIはアカウント作成、APIキー、ウェブダッシュボード、無料プランといったものが一切なく、利用したいときに直接APIに問い合わせ、料金を支払うことで必要な情報を取得できる仕組みだ。具体的には、オーストラリア企業のABN（Australian Business Number）などの企業情報を取得するAPIで、1回の問い合わせにつきわずか1セントで利用できる。このAPIは、支払いそのものがユーザーの認証となり、ログインのような役割を果たす点が特徴だ。

この支払いによる認証の仕組みは、HTTP 402 Payment Requiredというステータスコードを初めてその名の通りに利用している。通常、このエラーコードはあまり使われないものだったが、ここでは「支払いが必要です」という明確なメッセージとして機能する。まず、APIキーや認証情報なしでAPIを呼び出すと、サーバーからはHTTP 402ステータスコードと共に、機械が読み取れる形式の請求書がJSONデータとして返ってくる。この請求書には、支払うべき金額（例：USDCという仮想通貨で0.01ドルに相当する10000原子単位）、支払い先の仮想通貨アドレス、そしてこの支払いが何のサービスに対するものかといった情報が含まれている。

クライアントはこの請求書を受け取ると、EIP-3009という標準規格に沿って、指定された金額を支払い先アドレスに送金するための署名付き認証情報を生成する。この認証情報には、一度しか使えない署名を示すノンセ（nonce）という値が含まれる。生成した署名付き認証情報をBASE64という形式にエンコードし、「PAYMENT-SIGNATURE」というHTTPヘッダーに含めて、最初の時と同じAPIリクエストを再度サーバーに送信する。

サーバーは、この署名付き認証情報を受け取ると、x402ファシリテーターと呼ばれる外部の支払い処理仲介サービスに、その認証が有効かどうかを問い合わせる。ファシリテーターは署名を検証し、問題がなければBaseというブロックチェーンネットワーク上で実際に仮想通貨の送金（決済）を行う。決済が完了すると、ファシリテーターからサーバーに決済完了の通知が返され、サーバーは要求された企業データをクライアントに返す。このとき、「PAYMENT-RESPONSE」ヘッダーには決済のハッシュ値（取引を一意に識別する文字列）も含まれる。この一連のプロセスは、クライアントからの2回のAPI呼び出しと、サーバーからファシリテーターへの2回のAPI呼び出しで完結し、人間の介入は全く必要ない。サーバー自身はユーザーの仮想通貨の秘密鍵を保持せず、自分で送金のための署名も行わず、またブロックチェーンのガス代と呼ばれる手数料を支払うこともない。サーバーが行うのは、単に「お金が到着したかどうか」を確認する作業だけである。

このAPI開発の過程では、支払い情報のバージョン管理や支払い条件の確認方法について重要な学びがあった。APIが提示する支払い情報には、x402 v1とv2という二つの異なるバージョンが存在する。v1の支払い情報はJSONボディに記述され、v2はHTTPヘッダーにBase64形式で記述される。これらのバージョンは互いに完全に互換性があるわけではないため、v1クライアントはJSONボディだけを読み取り、v2クライアントはヘッダーだけを読み取ることで、それぞれ自身の理解できる形式で情報を受け取れるよう工夫されている。また、価格情報もv1ではmaxAmountRequired、v2ではamountという異なるキーで示されるが、両方のキーに同じ値を設定することで、クライアントがどちらのバージョンを想定しているか曖昧な場合でも、常に正しい価格を読み取れるようになっている。

セキュリティ面では、クライアントが提示する支払い条件のコピーが、サーバー自身の公開している利用規約と一致しているかを常に確認するようになっている。もしクライアントが自分に都合の良い条件を提示しても、サーバー側でそれを破棄し、常に正規の条件に基づいて検証を行うことで、不正な支払いを防ぐ。

また、ファシリテーターとの連携においてもいくつかの課題に直面した。クライアントとの通信はうまくいっても、ファシリテーターのAPI仕様が異なっていたために、サーバーからファシリテーターへの正しいとされるv2形式のリクエストが拒否されることがあった。結局、ファシリテーターはv1形式のリクエストしか受け付けないことが分かり、サーバーはクライアントのバージョンにかかわらず、常にv1形式でファシリテーターと通信するように修正された。これは、システムの一部が他のシステムと連携する際に、両者の仕様が完全に一致しているかを確認することの重要性を示している。

さらに、APIがファシリテーターの提供するサービスカタログに自動的に登録されることを開発者は知らなかった。最初の支払いが行われた時点で、APIはカタログに掲載されていたが、登録情報が最小限のものだったため、他の開発者からは見つけにくい状態だった。これは、APIが提供する情報をカタログを通じて広く公開するためには、特定の形式でメタデータ（APIの機能や説明など）を記述する必要があるという学びにつながった。v2形式で公開したメタデータがカタログに反映されなかったのは、ファシリテーターがv1形式の支払い情報からのみメタデータを読み取るためだった。このため、現在はv1とv2の両方の形式で、APIの発見性を高めるための情報が公開されている。サービス名のような情報にも文字数制限があることも判明し、細かな仕様の確認が重要であることが分かった。

課金に関する設計も、公正さを保つ上で非常に重要だ。例えば、検索クエリに合致するデータが見つからなかった場合（HTTP 404エラー）、このAPIは課金しない。支払いのための認証情報は解放され、別の検索に利用できる。これは、ユーザーが何の情報も得られなかった場合に料金を支払うべきではない、という考えに基づいている。最も難しかったのは、支払い処理中に通信が途切れて、サーバー側で送金が完了したかどうかが不明な場合への対応だった。以前のバージョンでは「課金されなかった」と報告していたが、これではユーザーが送金したのにデータを得られず、しかも同じ認証情報で再試行できないという問題があった。

この問題を解決するため、支払い認証に含まれるノンセ（一度しか使えない署名情報の一部）を「冪等性キー」として利用する仕組みが導入された。冪等性とは、同じ操作を何度行っても同じ結果になる特性を指す。具体的には、サーバーは支払い処理を開始する前に、APIレスポンスを生成して一時的に保存しておく。同じ支払い認証情報とクエリで再びリクエストが来た場合、サーバーは再課金せずに保存しておいたレスポンスを返す。もし送金状況が不明な場合は、「charged: "unknown"」というステータスを返し、ユーザーには同じリクエストと認証情報を再送するよう指示する。このとき、新しい認証情報を作成するのではなく、あくまで「同じものを再送する」のが重要だ。これにより、ユーザーは送金したお金を無駄にせず、最終的にデータを受け取れるようになる。さらに、データ取得はクエリ内容と支払者の署名の両方に厳密に紐付けられるため、他人が偶然知った認証情報を使ってデータを入手することはできないようになっている。Pythonのようなプログラミング言語での真偽値チェックの誤りにより、ファシリテーターからの「失敗」の応答が「成功」と誤認されるバグも見つかるなど、細かい実装上の注意点も明らかになった。

この新しいAPIは、例えば「woolworths」という企業名を指定してcurl -i "https://api.nightshiftbuilds.com/v1/company?name=woolworths"のように直接コマンドラインから呼び出すことで利用できる。最初の呼び出しで支払い情報が返され、その後支払いを実行して同じリクエストを再送するだけでデータが得られる。検索名が存在しない場合は費用はかからない。このAPIが提供するデータは、オーストラリア証券投資委員会（ASIC）の企業登録データから取得されたもので、週次で更新されるスナップショットであり、ASIC Connectが提供する公式の登録情報とは異なる点に注意が必要だ。