x402-compatible Agent Trial

agent_trial_lite_100 is one short-lived machine evaluation: one x402 v2 exact payment, 100 unique Lite report deliveries, and a 72-hour access grant. Re-reading the same Imprint does not spend another report unit. Failed or missing report lookups do not consume a unit.

This page describes an x402-compatible agent payment contract. It does not claim Cloudflare Wallets compatibility; that label requires a separate real-wallet test.

Availability and live quote

Always begin with GET /api/v1/agent/products. Continue only when the selected product returns available: true. The live response is the authority for amount, asset, network, pay-to address, product version, limits, and expiry.

The product advertises exactly three capabilities: fingerprint.submit, fingerprint.report.lite, and agent.trial.status.

The initial test fixture uses Base Sepolia (eip155:84532) and test USDC. Never infer a production network, asset, price, facilitator, or pay-to address from test documentation.

Create an intent

Send one exact 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"}

The HTTP 201 response returns intent_id, the one-time claim_token, status, a product summary (code, report_units, expires_in_hours, and report_depth), activate_url, and status_url. It does not return PAYMENT-REQUIRED; the first payment challenge comes only from the activation POST. EchoScan locks the full quote internally when it creates the intent.

Preserve the claim token only in process memory. Send it in Authorization: Bearer <claim_token>; it is never returned again and must never appear in a URL.

An origin must be a precise HTTP or HTTPS origin with no path, query, fragment, wildcard, bare domain, file://, or null value.

Pay with x402 v2

Call the returned activate_url without PAYMENT-SIGNATURE. A purchasable, unexpired intent responds with HTTP 402 and PAYMENT-REQUIRED. Before signing, compare amount, network, asset, and payTo in its exact requirement with the product-catalog snapshot taken before intent creation and the agent’s budget.

Use an official x402 HTTP client to retry the same POST with PAYMENT-SIGNATURE. A successful settlement response includes PAYMENT-RESPONSE. A client must retain the same intent ID and claim token across connection loss or response loss.

After submitting PAYMENT-SIGNATURE, the activation body contains only intent_id, status, and status_url; credentials are never delivered there. Poll the same intent before making any further activation attempt. A payment_in_progress, provisioning, reconciliation_pending, or active intent must not be paid again; recovery retains the original intent and resources.

Retrieve credentials safely

Poll the returned status_url with the claim token. An active response delivers top-level trial_id, status, environment_id, api_key, allowed_origin, quota (total_reports, used_reports, and remaining_reports), expires_at, and report_endpoint. It does not wrap these fields in a delivery object.

The API key is delivered only during the configured delivery window and responses use Cache-Control: no-store. Keep it in a server secret store. Do not persist it in browser storage or expose it to client code.

Produce and read reports

Run createEchoScan({ environmentId }).run() from the exact allowed origin. Browser Verifier returns only { imprint }. Send that value to trusted server code and query:

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

The trial provides Lite depth only. It does not provide Pro reasons, activity history, pick, submit-lite, billing, or renewal. The 101st new Imprint is rejected with a stable quota error; a retry of an already-delivered Imprint remains free.

Use GET /api/v1/agent/trial with the trial API key to read product_code, status, total_report_units, used_report_units, remaining_report_units, expires_at, capabilities, limits, remaining_submit_requests, and remaining_report_requests.

Expiry and recovery

The grant expires 72 hours after activation. New authenticated requests fail closed after expiry. Settlement or activation uncertainty is handled through status polling and reconciliation; the client must not discard the intent ID or attempt a second payment.

For executable schemas and header definitions, use /openapi.json. For the complete Browser Verifier boundary, use the developer guide.