Fresh402 Agent Intelligence

Fresh402 v2.5 — Web Intelligence API for AI Agents

Check whether a source changed, extract usable content, and compare structured snapshots. Pay per call with x402 or enabled native MPP USDC on Base, or use prepaid credits.

The hosted production API reports 2.5.1. Connect at fresh402.kirilllabs.workers.dev or its MCP endpoint. This documentation describes the hosted service; the repository's legacy implementation and backend release PR are maintained separately. A documentation release does not deploy the service.

Choose the operation

• Register once to establish a persistent baseline and receive a watch_id. Re-registering the same watch returns its existing baseline without loading the target again.
• Check before reusing a web source or spending on downstream browsing and reasoning. Get a change signal, noise filtering, conditional HTTP revalidation and an optional compact deterministic text diff. A cached Check is still a paid operation.
• Extract when an agent needs content for retrieval: text, titles, metadata, headings, links and JSON-LD from public HTML, JSON or text, with optional CSS scoping.
• Smart Diff when the change itself matters: compare a watch with its previous Smart Diff snapshot or fixed baseline, get structured additions/removals/modifications, and inspect significance scores with explainable deterministic rules.
• OpenAPI Contract Diff compares a registered public JSON OpenAPI 3.0/3.1 contract with a baseline or previous snapshot, returning conservative compatibility evidence. It does not resolve remote references or parse YAML.

Requests fetch eligible public HTTPS sources on demand. Fresh402 does not execute page JavaScript, render a browser, access authenticated sites, perform LLM-powered semantic analysis, continuously poll watches, or send push alerts. Security checks and rate, size, concurrency and operation limits apply; capacity failures may require a later retry.

Start with discovery

• Live OpenAPI 3.1 reference: current request schemas, examples, response formats and payment headers.
• Native MPP, SDK examples and recovery: inspect live enablement flags first. Base USDC EVM charge only; no newly real-money-validated MPP settlement is claimed.
• API guide, MCP integration, pricing, request examples.
• x402 resource manifest, agent guide, release notes.
• Official MCP Registry: the existing identity is io.github.kirillradchenko96/fresh402.
• Discovery audit: externally verified catalog status and outstanding reindexing or authorization requirements.

Free service metadata and MCP initialize / tools/list let a new agent learn all five tools without paying or fetching a target.

REST quick start

Register a baseline for free:

curl https://fresh402.kirilllabs.workers.dev/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/"}'

Use the returned watch_id in a Check or Smart Diff. The following unsigned request retrieves payment requirements, not a paid result:

curl -i https://fresh402.kirilllabs.workers.dev/v2/extract \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/","max_chars":20000}'

Expect HTTP 402 and a PAYMENT-REQUIRED header describing the exact amount, USDC asset, Base network and recipient. Use an x402 v2 compatible client and a payer-controlled wallet to authorize the exact amount, then retry the same request with PAYMENT-SIGNATURE. Never share a wallet seed phrase or private key. No unlimited token approval is required by the exact authorization flow.

Persist a client-generated recovery token before paying; the API guide explains the public client contract. A confirmed paid result carries a PAYMENT-RESPONSE settlement receipt. An HTTP 402 challenge is not a successful payment; a pending settlement must not trigger a replacement authorization.

MCP quick start

Add this URL as a remote Streamable HTTP MCP server in a compatible client:

https://fresh402.kirilllabs.workers.dev/mcp

The client performs initialize and tools/list; all five tools use the names and prices above. Free discovery does not require a Fresh402 API key. Paid tool calls require an x402-capable client; an ordinary MCP client can list tools and register a baseline but cannot automatically complete payment unless it implements x402.

MCP payment challenges are tool results with isError: true and requirements in structuredContent. HTTP 200 alone is not success. The payment belongs in params._meta["x402/payment"], and the settlement receipt is in result._meta["x402/payment-response"]. See MCP examples.

Public data and operational boundaries

Watch identifiers and legacy snapshot history are shared public service data. Do not use Fresh402 for private pages or submit secrets in target URLs. Free GET /v1/history and GET /v1/diff read retained legacy data without fetching a target; they do not expose paid Smart Diff results. Recovery tokens are private client credentials and must not appear in URLs, public repositories or logs.

The live API is the authority for the deployed contract. Catalog descriptions and cached schemas can lag it; the audit records that distinction. There is no claim that an unsigned 402 response proves Coinbase Bazaar indexing.

Built and maintained by Kirill Radchenko. Report an integration issue.

Self-service prepaid onboarding

Fresh402 2.4 provides wallet-authenticated account recovery and automatic finalized-payment reconciliation. Starter remains $2.50 / 1,000 credits and Developer $15 / 10,000 credits. Discover one-time packages and current credit costs in GET / → prepaid_packages; purchased credits do not expire. Check live purchasing availability before signing. See the account page, live availability, and customer API. Existing x402 and prepaid access operate independently; metadata never initiates a payment.

Browserless agent purchasing, bounded early credits and REST/MCP prepaid execution: exact quotes, local signer integration, spending caps and original-payment recovery. Read live availability before signing; early inclusion is not finality.

Optional Circle Gateway payments

Circle Gateway integration guide: optional Base USDC x402 batching for the four paid REST/MCP products. Acceptance is disabled pending real-money verification; inspect root circle_gateway.enabled. Existing Coinbase x402, native MPP and prepaid remain unchanged. Circle prepaid funding is unsupported.