Start here · API 3.0.2

From a URL to
repeatable evidence.

Production exposes eight MCP tools: free Register, four Web Intelligence operations and three finalized Base observation tools in a bounded commercial pilot. The canonical API and customer-account host is https://api.fresh402.com; the supported legacy workers.dev API shares existing account and prepaid identities. Only use these two trusted origins. Keep origin-bound signed payments and funding recovery at their original host.

1. Register a free baseline

No payment-aware client or API key is required. The source must be a public HTTPS document. Save the real returned watch_id and hash; illustrative IDs are not usable.

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

Repeating the identical canonical URL and rules returns the existing baseline without reloading. Register does not refresh an existing watch. Check does. A successful first registration performs a bounded fetch; availability, rate limits and source restrictions apply.

2. Use a normal HTTP client

JavaScript / Node.js

const origin = 'https://api.fresh402.com';
const response = await fetch(origin + '/v1/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com/' })
});
if (!response.ok) throw new Error('Registration HTTP ' + response.status);
const watch = await response.json();
console.log(watch.watch_id, watch.hash);

Python 3 (standard library)

import json, urllib.request
body = json.dumps({'url': 'https://example.com/'}).encode()
request = urllib.request.Request(
    'https://api.fresh402.com/v1/register',
    data=body, headers={'Content-Type': 'application/json'})
with urllib.request.urlopen(request, timeout=30) as response:
    watch = json.load(response)
print(watch['watch_id'], watch['hash'])

3. Connect MCP

Use a remote Streamable HTTP MCP client. SDK initialization, tools/list and the free Register tool are supported. Set the endpoint to:

https://api.fresh402.com/mcp

Use the tool's published input schema. A standard client without payment handling can discover all eight tools, but paid calls return a challenge. Configure an x402/MPP-capable client with explicit spending limits, or send a prepaid API key in the HTTP transport and the documented fresh402/prepaid call metadata. The URL alone does not authorize payments.

Tools are static: tools.listChanged=false. Unsupported subscription filters are rejected; an honored empty subscription subset ends without an open subscription.

Start free from an agent

Always free: discovery, MCP initialization and baseline Register within admission limits. Register saves or reuses a reference point; it does not continuously monitor or refresh an existing watch.

Machine evaluation: no funded wallet, purchase, dashboard or CAPTCHA. An existing EOA and permission to sign its exact EIP-191 ownership message are required. An ordinary MCP client without wallet-signing integration cannot enroll itself. Your wallet policy remains authoritative; do not give Fresh402 a private key.

1. Read live machine eligibility and limits. Stop if disabled.
2. POST /v3/agent-trial/challenge with {"wallet":"YOUR_EOA_ADDRESS"}. Sign only the exact returned message with your already-authorized wallet.
3. POST /v3/agent-trial/claim with wallet, challenge_id and signature. Persist the returned fm_ key privately. Never log it or put it in a URL.
4. Register your public HTTPS source, save its actual watch_id, then call Check with a trial key and a new persisted operation key. The same tool, input and key recover the retained result without fresh work.
5. GET /v3/agent-trial/quota with the key to inspect remaining allowance. Return later with the same watch and a new operation key for a new comparison.

const origin = 'https://api.fresh402.com';
// Load trialKey and operationId from your private store; never print them.
// Save operationId + exact input BEFORE the first submission.
const input = {watch_id: savedWatchId, max_age_seconds: 0};
const response = await fetch(origin + '/v1/check', {
  method: 'POST', redirect: 'error',
  headers: {'Content-Type': 'application/json',
    'X-Fresh402-Trial-Key': trialKey, 'Idempotency-Key': operationId},
  body: JSON.stringify(input)
});
const result = await response.json();
if (!response.ok) throw new Error('Trial HTTP ' + response.status);
// Persist the result privately; never automatically fall back to payment.

Current one-time machine allowances: 2 Checks and at most 1 each of Extract, Smart Diff, OpenAPI Diff, Contract Watch, Wallet Watch and Token Facts. Maximum credential lifetime is 7 days, clipped to November 14, 2026 09:00 UTC. Rotation preserves quotas and original expiry. Human Web trial allowances remain separate.

Shared best-effort capacity, not a reserved bundle: 32 weighted units/day, 64/month, 8/network/day; web attempts reserve 120 seconds each against 360 seconds/day and 1,200 seconds/month globally. Thus the machine pool admits at most 3 web attempts/day and 10/month across all identities, before other limits and failures. One new machine identity/network/day; one concurrent free operation; blockchain reserves at most one bounded 18-RPC operation/day across machine trials. Legitimate shared-cloud clients can hit these limits. Failed work restores the tool allowance, not infrastructure reservations.

429 means quota, rate or capacity pressure; 503 means unavailable. Neither permits a charge. Exhaustion does not purchase anything. Read your quota, retain your original operation and explicitly choose paid continuation only if authorized. A 50/100-Check, 30-day offer is not live.

Exact machine enrollment and recovery contract · Wallet-policy-neutral challenge/claim adapter

Use the tested source SDK

The Fresh402 Efficiency SDK 0.3.5 is a source-based Node.js 24+ / TypeScript client foundation, not an npm package. It supplies tool bindings, explicit budget guards, evidence caching, prepaid CreditSession, original-operation recovery and machine challenge/claim helpers. OpenAI Agents SDK, LangChain/LangGraph and Coinbase AgentKit adapters are optional. It does not supply wallet authority, sign by itself, fund an account or guarantee that a model picks the right tool.

git clone --depth 1 --single-branch --branch efficiency-sdk-v0.3.5 https://github.com/kirillradchenko96/fresh402.git
cd fresh402
node examples/efficiency/quickstart.ts

This first run needs no dependency installation and obtains discovery and one unpaid quote only. It does not execute a product or prove free usage. For a useful free result, follow the machine workflow above with an eligible credential. Inspect the SDK guide and two tested agent jobs. Paid execution is opt-in; keep private budgets, original keys and proofs outside Git.

When Fresh402 helps, and when it does not

Use reusable watches and supported normalization when several sessions need a common reference point; use bounded structural differences and private durable operation recovery to reduce orchestration. An unchanged Check is compact evidence, not the full document. Exact selection and comparison modes matter: text normalization can miss link-only changes unless the documented attribute mode is selected. No background monitoring or JavaScript rendering is implied.

A direct HTTP fetch with your own ETag cache or a local diff library can be simpler and cheaper for one source you already manage. Generic JSON/text tools and an established OpenAPI comparator can outperform a service roundtrip; Fresh402 does not claim universal accuracy, latency or token savings. Its differentiated benefit is persistent shared observations and recoverable orchestration. Read the per-tool inputs, outputs and limitations before choosing.

Human free-trial pilot

Check /v2/trial for actual availability. Authenticated Web trials are enabled in 3.0.2 within finite shared capacity. A disabled pilot cannot execute free calls. the trial page uses an unfunded EOA ownership signature plus human verification to issue a separate trial key. One-time quotas: Check 20, Extract 10, Smart Diff 5, OpenAPI Diff 3. Shared capacity can be unavailable before an identity exhausts its allowance. Human Web trial allowances exclude blockchain. The separate machine trial at /v3/agent-trial requires an exact wallet-control signature without human CAPTCHA; root machine_trial.enabled, network/global admission and shared quotas are authoritative.

Send X-Fresh402-Trial-Key and a privately persisted Idempotency-Key to the normal REST tool path or MCP HTTP transport. Use a new key for each new logical operation; reuse it with exactly the same tool and parsed input for recovery. MCP clients must set that header per logical call, not reuse one constant key for every tool call. No proprietary trial MCP metadata is required. Never mix trial keys with prepaid keys, payment signatures or recovery credentials.

Trial responses are retained for seven days; expired retained results return terminal errors and never rerun work. A fresh wallet proof rotates the credential without resetting entitlements. Failed execution releases its tool allowance, while infrastructure cost reservations remain consumed. One wallet is not proof of one human; network, CAPTCHA and global limits also apply.

4. Pay only when you choose

Open the canonical account page for prepaid onboarding and a package quote. Current tariffs are Check 2 / Extract 3 / Smart Diff 4 / OpenAPI Diff 5 credits. Packages cost $2.50 / 1,000 credits or $15 / 10,000 credits and are one-time nonexpiring purchases.

For prepaid execution, use the matching prepaid REST path, X-Fresh402-API-Key, a persisted idempotency key, the quoted tariff version and your maximum authorized credit charge. Different accounts may have legacy terms; read your authenticated quote. Never log credentials or include them in URLs.

x402 v2 and native MPP use native USDC on Base (chain ID 8453), recipient Safe Treasury 0xFAC492A8D7843C9aFCCa6A1691BCCB5425ab14F3. Validate this recipient against the live quote before signing; stop on a mismatch. The Safe is currently 1-of-1, not independent multisignature protection or escrow. Preserve the original recipient and proof when recovering an older payment. No unlimited allowance is needed. See current prices and the full API reference.

Persist original payment proof, input, private recovery token or prepaid idempotency key before submitting. Retry the original operation after uncertainty; never sign a replacement. A settlement receipt and durable result are separate evidence from a quote or HTTP 402 challenge.

Finalized Base observation pilot

Bounded commercial pilot on Base mainnet. x402 and native MPP are available at the quoted per-call prices. New all-service Starter and Developer packages cover all seven paid tools after explicit all-service terms acceptance; existing Web credits keep their original rights and do not automatically gain blockchain access. Only finalized all-service credits fund blockchain calls. Human Web trials do not cover blockchain; the separate machine trial may admit one bounded observation within its shared18RPC/day cap. Finalized single-provider observations only, with finite shared daily capacity; no trading, safety score or complete history.

Contract Watch $0.010 / 4 all-service credits; Wallet Watch $0.020 / 8 all-service credits; Token Facts $0.010 / 4 all-service credits. See the tool reference and the live OpenAPI schema. Preserve the original proof, input and private recovery token before authorizing x402 or MPP.

Errors worth handling

400/422: correct the input or scope. 403: access denied. 409: original operation pending or key/input mismatch; preserve the key. 410: retained result expired; no automatic reexecution. 429: quota, rate or capacity pressure; honor Retry-After. 502–504: bounded upstream failure; inspect original payment state before any further authorization.

Machine-readable OpenAPI · Root discovery · Security and limitations