fresh402_check
Check whether public HTML, JSON or text changed; optional html_attributes on a new URL watch detects same-text link and selected attribute changes without altering older watches; use for on-demand freshness checks and a compact deterministic text diff, not background monitoring. Supply exactly one of url or watch_id. A URL-based paid Check can create a watch; an ID reuses its saved URL/rules, so omit all content-rule fields. Reuse returned watch_id/hash for later checks; first URL check without prior state reports changed:null. Optional cache reuse still costs $0.005 USDC per call on Base mainnet (eip155:8453). Requires an x402-capable MCP payment client and funded native-USDC payer; an ordinary MCP client receives a payment challenge, not a paid result. Alternatively use prepaid credits through REST or this MCP tool: X-Fresh402-API-Key in HTTP, with params._meta["fresh402/prepaid"] containing idempotency_key, tariff_version and max_credits. When root mpp_payments.enabled is true, native MPP EVM charge is another option at the same USDC price: use an authorized Base EIP-712 signer and official mppx client, org.paymentauth/credential metadata and a persisted private recovery token. MPP receipt: org.paymentauth/receipt; see docs/MPP.md. Never combine MPP, prepaid and x402. Discover packages at /v2/prepaid/plans; see docs/AGENT_PREPAID.md for browserless wallet enrollment, bounded early credits and recovery. No JavaScript execution. Optional Circle Gateway x402 is available only when root circle_gateway.enabled is true. Use the GatewayWalletBatched quote, a funded Base Gateway EOA and a persisted private recovery token. Pending batches return 409; replay the original proof/input/token after 60 seconds. Results require Gateway confirmed/completed evidence; never mix providers. No Circle prepaid funding. See docs/CIRCLE_GATEWAY.md. Optional free evaluation: inspect GET /v3/agent-trial for the CAPTCHA-free machine trial (unfunded EOA ownership signing required). Web tools may also use the separate human trial at /v2/trial. Only enabled, eligible allowances authorize free execution; shared capacity can return 429 earlier. Send X-Fresh402-Trial-Key and a distinct persisted Idempotency-Key per logical REST or MCP call. Reuse the same tool/input/key for retained recovery. Never mix trial and payment/prepaid credentials. Exhaustion never authorizes a charge; ordinary requests without trial credentials retain the paid challenge.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Supply exactly one of url or watch_id. URL must be absolute public HTTPS on port 443, at most 4096 characters, with no credentials/private targets, e.g. 'https://example.com/docs'. Fresh402's own service URLs, including its discovery /openapi.json, cannot be targets; choose an external public document. With url, optional content rules identify the watch; an existing watch is reused or a new one is created by this paid Check. Separate registration is not required. No JavaScript rendering. | |
| selector | No | Optional HTML CSS scope, 1-256 characters, e.g. 'main'; accepted only with url. Omit for the page after built-in noise removal. No match returns 422; not supported for JSON/plain text. With watch_id, omit this field: the saved selector is reused. | |
| watch_id | No | Supply exactly one of watch_id or url. An existing ID returned by fresh402_register (free), POST /v1/register, or a URL-based Check: 'w_' followed by 32 lowercase hexadecimal characters. Reuses that watch's stored URL and rules. When supplied, omit selector, ignore_selectors and ignore_json_paths entirely, even empty arrays. Do not invent an ID. | |
| include_diff | No | Optional boolean; runtime default: true. Request a compact deterministic text diff when content changed and compatible prior text is retained. False omits the diff; true cannot recover unavailable old content and does not enable Smart Diff's structural analysis. | |
| previous_hash | No | Optional previous Fresh402 content hash: exactly 64 hexadecimal characters, case-insensitive. Overrides comparison with the watch's current stored hash. Omit to use that stored hash; a new URL watch without a prior hash returns changed:null. Hash comparison does not require retained old text, but a text diff does; a hash cannot reconstruct missing content. | |
| html_attributes | No | Optional HTML-only watch rule: up to4 of href,title,alt,aria-label; default[] retains existing text-only normalization. Distinct names are sorted; nonempty rules create a separate version1 watch/baseline. Records bounded meaningful attributes within the saved selector or filtered page, including same-text link destination changes. Cannot be supplied with watch_id, even[]. Unsafe hrefs are hashed, never fetched. Limits:200 elements,2048 characters/value,32768 evidence bytes; excess fails, never clips silently. | |
| max_age_seconds | No | Optional integer cache age in seconds, 0-86400; runtime default: 0. A positive value permits reuse of a sufficiently recent watch result without fetching. Zero contacts the source (conditional HTTP may return 304). Cached Checks still require payment; this does not schedule background polling. | |
| ignore_selectors | No | Optional HTML-only exclusion array, up to 20 supported CSS selectors of 1-256 characters each, e.g. ['.timestamp']. Accepted only with url; default []. With watch_id, omit the field entirely (including []): saved exclusions are reused. | |
| ignore_json_paths | No | Optional JSON-only exclusions, up to 20 paths of 1-256 characters starting with '/'; '~0'/'~1' escapes and '*' segments are supported. Example: ['/updated_at']. Accepted only with url; default []. With watch_id, omit entirely (including []): saved paths are reused. |