endpoint_spot_check
Decision-shaped 402xAgent check of a public URL (private, loopback and link-local addresses blocked on every redirect hop) for an x402 PAYMENT-REQUIRED / 402 challenge. Every answer has reason_code (stable code) and confidence (high|medium|low); rules: https://402xagent.com/rules.json. History: stable_for_days, last_changed, drift, days_observed, first_seen, last_checked. Free: verdict (pay|skip|recheck), a plain-words reason, payment_terms_sha256 (hash of the approved payment), and access. Paid: verdict, reason code, quoted/claimed price, pay_to, network, asset, and payment = the exact {network, asset, amount_atomic, amount_usd, pay_to} a router may sign (verdict pay only), plus access with the settlement tx. No 402 terms is skip/no_paywall (recheck/free_trial_active when the target sends x-free-trial headers); recheck only for timeouts, 5xx, network errors and (0.55.0) HTTP 429 (rate_limited), a 403 with a firewall/WAF challenge signature (waf_challenge) or a host that still does not resolve after one retry (dns_error); after 24 h (TRANSIENT_SKIP_AFTER_HOURS) of only those rechecks the endpoint falls back to skip (*_persistent); (0.56.0) recheck/timeout when the whole probe (redirects + body) exceeds PROBE_TIMEOUT_MS (default 8000 ms), and recheck/host_unstable while the per-host circuit breaker is open (3 failed probes of the host in 10 min -> 15 min pause; target not fetched, no free check used, never charged); (0.57.0) before a live pay (after the free check or payment is accepted) a second quick probe of the same target must read the same 402 terms (scheme, network, asset, payTo; amount within 1%): different terms are recheck/terms_unstable, a failed confirm probe is its own recheck (server_error, timeout, unreachable); same price and free check; a plain 403 stays skip/no_paywall; wrong or unsupported network, non-canonical USDC or a pay_to that differs from the listing is skip. The same normalized URL + method reuses one probe for 5 min, so consecutive calls agree. mode=dry-run: free dry run (nothing signed or paid, stored as a public receipt, no approval hash, 50/caller/day). Never pays the target (probe GET only). 5 free checks per client per UTC day (at most 25 per network) (client=vc-mcp), then $0.02 USDC a check on Base via x402. Unpaid after free quota: payment instructions. Forward PAYMENT-SIGNATURE for a paid check.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"url": "<url>"
},
"name": "endpoint_spot_check"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | optional attribution tag stored on the receipt (dry-run-<caller> sets mode=dry-run) | |
| url | Yes | public http(s) URL to probe | |
| mode | No | optional: dry-run = free dry run: one unpaid probe, nothing signed or paid, always stored as a public receipt (check_type dry-run). Returns the free-tier shape with payment_terms_sha256 null (never an approval). 50 per caller (ref, else client, else IP) per UTC day. ref=dry-run-<caller> also sets it | |
| task | No | optional task label (ignored in decision output) | |
| quote | No | optional (0.54.0): the receipt id you were quoted (a discover/crawl id, 10 hex, or a live sc- id). If the live terms (price, pay_to, network, asset) differ from it, the answer is recheck/terms_changed_since_quote instead of pay | |
| method | No | optional: probe the target with POST (empty JSON body) for POST-only endpoints | |
| pay_to | No | optional: the wallet you expect to pay (from your listing) | |
| network | No | optional: the CAIP-2 network you expect, e.g. eip155:8453 | |
| claimed_price | No | optional claimed USD price to compare vs quoted |