Agent API

Machine clients discover EchoScan through the API Catalog and OpenAPI contract, then check the live product catalog before starting an Agent Trial purchase.

Discover the contract

• /.well-known/api-catalog is the RFC 9727 API Catalog.
• /openapi.json defines the Agent Trial, x402 headers, schemas, statuses, and canonical Report contract.
• /llms.txt is the compact discovery index.
• Developer API documentation covers Browser Verifier and Report API v1.
• Production MCP documentation covers human Workspace access through OAuth.

Check availability

Call GET https://api.echoscan.org/api/v1/agent/products. Continue with agent_trial_lite_100 only when available is true. The returned product snapshot is authoritative for price, asset, network, duration, capabilities, and limits.

The Agent Trial capabilities are fingerprint.submit, fingerprint.report.lite, and agent.trial.status.

Purchase and activate

1. Create an Intent for one exact HTTP or HTTPS Origin. Retain intent_id, the one-time claim token, activate_url, and status_url.
2. Keep the claim token in process memory and send it only as a Bearer credential.
3. Request activate_url and read the HTTP 402 PAYMENT-REQUIRED challenge.
4. Verify the challenge against the locked product snapshot and the client’s spending policy.
5. Retry the activation request with an x402 v2 exact-payment client and PAYMENT-SIGNATURE.
6. Read PAYMENT-RESPONSE, then poll status_url for recovery and credential delivery.
7. During the delivery window, store the returned Environment ID and Agent Trial API key in their correct browser/server boundaries.

GET /api/v1/agent/trial returns the active grant, purchased limits, usage, remaining quota, capabilities, and expiry for the Agent Trial API key.

Credential boundaries

The Environment ID is publishable and is used by Browser Verifier at the exact allowed Origin. The claim token, payment credential, and Agent Trial API key are secrets. Keep them out of URLs, prompts, browser persistence, logs, metrics, and committed files.

The Agent Trial API key is limited to canonical Report retrieval and Agent Trial status according to the live product contract.

Interpret the Report

Use risk.status, risk.reasons, and risk.findings as input to the customer’s own allow, challenge, review, or deny policy. The Report describes device and access-risk evidence, not a person’s legal identity or intent.