ECHOSCAN
UNQ
STB
#···
关于 博客

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.submitfingerprint.report.liteagent.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_tokenstatus、包含 code / report_units / expires_in_hours / report_depthproduct 摘要、activate_urlstatus_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 要求的 amountnetworkassetpayTo 与创建 Intent 前保存的产品目录快照以及 Agent 预算逐项对比。

使用官方 x402 HTTP Client,通过 PAYMENT-SIGNATURE 重试同一个 POST。结算成功时响应包含 PAYMENT-RESPONSE。即使连接或响应丢失,客户端也必须保留同一个 Intent ID 和 claim token。

提交 PAYMENT-SIGNATURE 后,Activate Body 只包含 intent_idstatusstatus_url,不会交付凭证。在任何下一次激活尝试前先查询同一个 Intent。当状态为 payment_in_progressprovisioningreconciliation_pendingactive 时不得再次付款;恢复流程会保留原 Intent 和资源。

安全领取凭证

携带 claim token 轮询响应中的 status_urlactive 响应从顶层交付 trial_idstatusenvironment_idapi_keyallowed_origin、包含 total_reports / used_reports / remaining_reportsquotaexpires_atreport_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_codestatustotal_report_unitsused_report_unitsremaining_report_unitsexpires_atcapabilitieslimitsremaining_submit_requestsremaining_report_requests

过期与恢复

Grant 在激活 72 小时后过期,过期后的新鉴权请求立即 Fail Closed。结算或激活结果不确定时,通过 Status 轮询和 Reconciliation 恢复;客户端不能丢弃 Intent ID 或再次付款。

接口 Schema 与 Header 定义见 /openapi.json,完整 Browser Verifier 安全边界见开发者指南