x402 兼容 Agent Trial
agent_trial_lite_100 是一次短期机器评估:一笔 x402 v2 exact 付款、100 个唯一 Imprint 的 Lite Report 首次交付,以及 72 小时 Access Grant。重复读取同一 Imprint 不会再次扣除 Report Unit;失败或不存在的 Report 查询也不扣除。
本页描述的是 x402-compatible agent payments 合同,不声称已经支持 Cloudflare Wallets;该文案必须等真实 Wallet 测试通过后才能使用。
可购买状态与实时报价
始终先调用 GET /api/v1/agent/products。只有选定产品返回 available: true 时才继续。金额、资产、网络、收款地址、产品版本、限制和有效期都以实时响应为准。
产品只公布三个精确 Capability:fingerprint.submit、fingerprint.report.lite 和 agent.trial.status。
初始测试 Fixture 使用 Base Sepolia(eip155:84532)和 Test USDC。不能根据 Testnet 文档推断 Production 的网络、资产、价格、Facilitator 或收款地址。
创建 Intent
提交一个精确 Origin:
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,通过 PAYMENT-SIGNATURE 重试同一个 POST。结算成功时响应包含 PAYMENT-RESPONSE。即使连接或响应丢失,客户端也必须保留同一个 Intent ID 和 claim token。
提交 PAYMENT-SIGNATURE 后,Activate Body 只包含 intent_id、status 和 status_url,不会交付凭证。在任何下一次激活尝试前先查询同一个 Intent。当状态为 payment_in_progress、provisioning、reconciliation_pending 或 active 时不得再次付款;恢复流程会保留原 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 安全边界见开发者指南。