x402互換Agent Trial

agent_trial_lite_100は短期間の機械評価プランです。x402 v2のexact支払い1回で、100件の一意なImprintに対するLite Reportの初回交付と、72時間のAccess Grantを取得します。同じImprintの再照会、失敗した照会、存在しないReportの照会ではReport Unitを消費しません。

本ページが説明するのは x402-compatible agent payments の契約です。Cloudflare Walletsへの対応は、別途実施する実ウォレットテストに合格するまで表明しません。

購入可能状態と最新の見積もり

必ずGET /api/v1/agent/productsから開始してください。選択した商品がavailable: trueを返す場合だけ先へ進みます。金額、アセット、ネットワーク、受取先、商品バージョン、上限、有効期間は最新レスポンスを正とします。

商品が公開するCapabilityは、正確にはfingerprint.submit、fingerprint.report.lite、agent.trial.statusの3つだけです。

初期テストFixtureはBase Sepolia（eip155:84532）とTest USDCを使います。テスト情報から本番のネットワーク、アセット、価格、Facilitator、受取先を推測してはいけません。

Intentを作成する

正確なOriginを1件送信します。

POST https://api.echoscan.org/api/v1/agent/trial-intents
Content-Type: application/json

{"product_code":"agent_trial_lite_100","origin":"https://agent.example"}

HTTP 201レスポンスにはintent_id、一度だけ表示されるclaim_token、status、code / report_units / expires_in_hours / report_depthを持つproduct概要、activate_url、status_urlが含まれます。このレスポンスはPAYMENT-REQUIREDを返しません。最初の支払いチャレンジはActivate POSTだけが返します。EchoScanはIntent作成時に完全な見積もりをサーバー側で固定します。

claim tokenはプロセス内だけに保持し、Authorization: Bearer <claim_token>で送信します。以後のレスポンスでは再表示されず、URLへ入れてはいけません。

Originには正確なHTTPまたはHTTPS Originを指定します。Path、Query、Fragment、Wildcard、裸のドメイン、file://、nullは指定できません。

x402 v2で支払う

PAYMENT-SIGNATUREなしでレスポンスのactivate_urlを呼び出します。購入可能で有効なIntentはHTTP 402とPAYMENT-REQUIREDを返します。署名前に、exact要件のamount、network、asset、payToを、Intent作成前に保存した商品カタログのスナップショットおよびAgentの予算に照らして確認してください。

公式x402 HTTP Clientで同じPOSTをPAYMENT-SIGNATURE付きで再試行します。決済成功レスポンスにはPAYMENT-RESPONSEが含まれます。接続またはレスポンスを失っても、同じIntent IDとclaim tokenを保持してください。

PAYMENT-SIGNATUREを送信した後、Activate Bodyに含まれるのはintent_id、status、status_urlだけで、認証情報は交付されません。次の有効化を試す前に同じIntentを照会します。payment_in_progress、provisioning、reconciliation_pending、activeのIntentへ再度支払ってはいけません。復旧時も元のIntentとリソースが維持されます。

認証情報を安全に取得する

claim tokenを付けてレスポンスのstatus_urlをポーリングします。activeレスポンスは、トップレベルのtrial_id、status、environment_id、api_key、allowed_origin、total_reports / used_reports / remaining_reportsを持つquota、expires_at、report_endpointを交付し、deliveryでラップしません。

API Keyは設定された交付期間中だけ返され、レスポンスにはCache-Control: no-storeが設定されます。サーバー側のSecret Storeへ保存し、ブラウザの永続ストレージやクライアントコードへ公開しないでください。

Reportを生成して照会する

正確なAllowed OriginからcreateEchoScan({ environmentId }).run()を実行します。Browser Verifierが返すのは{ imprint }だけです。信頼できるサーバー側コードへ渡し、次を照会します。

GET https://api.echoscan.org/api/v1/fingerprint/report/{imprint}
X-API-Key: <agent_trial_api_key>
Accept: application/json

TrialはLite深度だけを提供します。Pro Reasons、Activity History、Pick、submit-lite、Billing、Renewalは利用できません。101件目の新しいImprintは安定したQuota Errorで拒否され、交付済みImprintの再試行は無料です。

Trial API KeyでGET /api/v1/agent/trialを呼び出すと、product_code、status、total_report_units、used_report_units、remaining_report_units、expires_at、capabilities、limits、remaining_submit_requests、remaining_report_requestsを確認できます。

有効期限と復旧

Grantは有効化から72時間後に失効し、それ以降の新しい認証リクエストはFail Closedになります。決済または有効化の結果が不明な場合は、StatusポーリングとReconciliationで復旧します。Intent IDを破棄したり、再度支払ったりしてはいけません。

実行可能なSchemaとHeader定義は/openapi.json、Browser Verifierの完全な境界は開発者ガイドを参照してください。