Agent API

Agent Trialの商品カタログがavailable: trueを返す環境では、AI Agentが標準APIからEchoScanを発見し、購入してリスクチェックを評価できます。購入機能が無効でもディスカバリー情報は参照できるため、支払い前に必ず最新の商品レスポンスを確認してください。

EchoScanはデバイス識別とアクセスリスクのAPIです。暗号資産サービスではなく、ブラウザ利用者にウォレット接続を求めることもありません。

公開仕様を発見する

• /.well-known/api-catalog はRFC 9727準拠のAPIカタログです。
• /openapi.json はAgent TrialとLite Reportのエンドポイントを定義します。
• /llms.txt はAgent向けの簡潔な製品・セキュリティ索引です。
• 開発者向けAPIドキュメント はBrowser VerifierとReport API v1を説明します。

HTTPレスポンスでもapi-catalog Link Relationを通知します。このリリースではMCP ServerおよびMCP Server Cardを公開しません。

購入可能か最初に確認する

GET https://api.echoscan.org/api/v1/agent/productsを呼び出します。agent_trial_lite_100のavailableがtrueの場合だけ先へ進み、レスポンスに含まれる価格、アセット、ネットワーク、有効期間、Capability、制限を最新の契約として扱います。

この商品のCapabilityは、正確にはfingerprint.submit、fingerprint.report.lite、agent.trial.statusの3つです。

公開ページには本番価格や受取アドレスを固定値として記載しません。支払い設定が無効または不完全な場合、サービスはFail Closedで購入不可を返します。

Agent Trialを完了する

1. 正確なHTTPまたはHTTPS Originを1件指定してIntentを作成し、レスポンスのproduct、activate_url、status_urlを保持します。
2. 一度だけ表示されるclaim tokenはプロセス内だけに保持し、Bearer認証で送信します。
3. 支払い情報なしでActivate URLを呼び出し、HTTP 402のPAYMENT-REQUIREDを読み取ります。
4. チャレンジが固定済みの見積もり、予算、ネットワーク、アセット、受取先と一致することを確認します。
5. x402 v2のexact対応HTTP ClientでPAYMENT-SIGNATUREを付けて再試行します。
6. Status URLをポーリングし、交付期間内にトップレベルのtrial_id、Environment ID、API Key、Allowed Origin、Quota、有効期限、Report Endpointを取得します。
7. 正確なAllowed OriginからBrowser Verifierを実行し、{ imprint }をサーバー側コードへ渡して、正規のLite Reportエンドポイントを照会します。

再試行、上限、有効期限、認証情報の境界はx402互換Agent Trialガイドを参照してください。

Agentの記録に秘密情報を残さない

購入者の秘密鍵、claim token、PAYMENT-SIGNATURE、EchoScan API KeyをURL、プロンプト履歴、ブラウザの永続ストレージ、ログ、メトリクスラベル、コミット対象ファイルへ入れてはいけません。Environment IDは公開可能ですが、Agent Trial API Keyと支払い情報は秘密です。

Trial Keyで利用できるのはLite Reportと自身のTrialステータスだけです。Pro Reasons、History、Pick、submit-lite、Billing、Console Session、Internal Routeにはアクセスできません。

Lite Reportを判断に使う

risk.statusは、導入先が行うallow、challenge、review、deny判断の材料として利用します。LiteにはPro ReasonsやActivity Historyが含まれず、EchoScanが個人の法的身元や意図を証明することもありません。