check
Probe a live paid API endpoint or discovered candidates, apply your price, network, and readiness rules, and get a signed offer quote with seller terms before paying.
Instructions
Runs the paid pre-flight check on a live paid API endpoint: probes one exact HTTPS url, or the candidates discovered for a need, applies the buyer's price, network and readiness rules, and returns the selected offer with signed evidence of what the seller quoted (price, recipient, asset, network, expiry) before the agent pays the seller. Does not buy the seller's service, hold keys or pay anything for the agent; the agent keeps its wallet and pays the seller separately.
Use preview to discover candidates without paying, validate for a free readiness check of one listed URL, and check when a fresh live observation or a signed receipt is needed before a seller payment. Never call check to pay a seller. After billing.settlement_state=unknown, stop and reconcile; never create another authorization. route is the former name of this tool and is still accepted.
Cost and outcomes: the first unsigned call answers HTTP 402 with the $0.003 USDC checking-fee terms (Base, Solana or Algorand), which an x402-capable HTTP client pays. The fee settles only when a qualifying live offer is found; a completed miss (HTTP 200, live=false, typed miss_reason) is free; a settled fee is not reversed if the offer later changes. HTTP 503 with binding_error=route_binding_unavailable means the seller answered but no probed candidate could be bound to a signed receipt: a completed unpaid answer, not an outage (the reference wrapExactAuthorize reports state=binding_unavailable with keep_calling_route true).
Parameter interactions: need or url is required; with both, url is probed directly and no discovery runs. policy is plain English compiled into the structured fields; an explicit structured field wins over the compiled value, and phrases that do not compile are echoed in unresolved_constraints, never guessed. networks is a hard allowlist judged on the current 402; prefer_network only orders results and never filters. Three independent price bounds: max_price_usd (seller price in USD), max_amount_atomic (atomic units of the seller's asset) and max_total_cost_usd (seller price plus known fees); every bound fails closed when its value is unknown. require_route_binding=true implies require_transparency and may select the next bindable candidate. Defaults: objective best, search_depth standard (up to 7 probes; thorough up to 15; hard ceiling 20), accept_payTo_change false, require_route_binding false. Guide: https://402signal.com/developers#route-binding
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional https URL to probe instead of discovery. need or url (or both) is required. | |
| need | No | What the caller wants routed (plain English). | |
| policy | No | Natural-language constraints compiled into structured values. Unresolved phrases are returned, never guessed. | |
| networks | No | Hard policy lock. Restricts discovery and selection to this set. A HTTP 200 winner must have selected_payment.network in this set from the CURRENT observed 402, never a catalog claim. Unlike prefer_network, this is not a ranking preference. | |
| objective | No | Best-of-N among currently probed eligible candidates, not every discovered endpoint. cheapest, fastest, and most_reliable rank that probed survivor set. fastest is this-request probe RTT, not settlement latency. fastest_settlement is a separate settlement/finality objective. lowest_total_cost fails closed when a fee is unknown. | |
| search_depth | No | standard: first 3 then expand 2-4 (typical cap 7). thorough may expand further. Hard server ceiling is 20. | |
| max_price_usd | No | Drop live hits whose known normalized USD exceeds this bound. Unknown USD fails closed. | |
| max_latency_ms | No | Compatibility alias for max_probe_latency_ms (this request's probe RTT). Unknown latency fails closed. | |
| prefer_network | No | Weak ranking preference only. Ranks this seller network first but still searches and selects across all supported networks. Not a filter. Use networks for a hard policy lock. Observed networks: base, solana, algorand and the EVM chains polygon, arbitrum, monad, worldchain, xlayer, bnb, hyperevm, ethereum, optimism, avalanche, tempo, sei, celo, robinhood (CAIP-2 ids such as eip155:137 are accepted); the checking fee itself is paid on base, solana or algorand. | |
| min_observations | No | Require history n_7d at least this large. Unknown or smaller fails closed. | |
| max_amount_atomic | No | Drop live hits whose known atomic amount exceeds this bound. Unknown or cross-asset amount fails closed. | |
| require_invocable | No | If true, drop live hits without an input schema. An explicit empty-object schema (type object, no properties or required fields) advertises no required inputs and counts as present. A bazaar HTTP GET with empty queryParams and no required body is the same signal. It does not guarantee the seller call succeeds. Absent or refused schema is not invocable. | |
| max_total_cost_usd | No | Merchant price plus known fees. Unknown fee fails closed. | |
| accept_payTo_change | No | If true, allow selecting a destination whose payTo just changed for the first time. Default false: the first unexpected payTo change is not selectable; a second later independent observation of the same destination can establish it. | |
| max_probe_latency_ms | No | Drop live hits whose known probe RTT exceeds this bound. Not historical service/p50 latency. | |
| min_observed_success | No | Require observed success_7d when n_7d >= 3. Unknown fails closed. | |
| min_reputation_score | No | Require V1 reputation_score. Unknown fails closed. Never guessed from vague NL. | |
| require_transparency | No | If true, a settled /route winner fails when a signed checkpoint receipt cannot be produced. This requires delivery of verifiable evidence on HTTP 200, not server-side recovery. To verify the routing decision later, securely retain the complete paid /route response, especially pq_trust.transparency.receipt and pq_trust.transparency.reveal. Private replay outcomes support bounded recovery of the original response; they are not long-term evidence storage. Keep your own copy. Modified evidence fails verification against the public log. Default false (SEC-ROUTER-004 / A-14): a settled winner does not require a durable signed leaf. A free typed miss creates no route-decision leaf. Routing continues if append, signing, or anchoring is down after settlement (logged_uncheckpointed or unavailable). logged_uncheckpointed is never success when this flag is true. require_route_binding=true also requires transparency, even if this flag is false. A required receipt failure after settlement still reports billing.settled=true; unavailable does not prove no append occurred. | |
| require_route_binding | No | Opt in to proof_carrying_route_v1 and a signed v4 receipt. Requires exact x402 v2 terms observed on the same HTTPS URL, method and probe body, without redirects or unresolved policy. If the ranked winner cannot bind, the router may fall through to the next already-probed selectable candidate that can; there is no unguarded settle. HTTP 503 route_binding_unavailable only when none remain bindable (a free typed miss). wrapExactAuthorize reports state=binding_unavailable with keep_calling_route true; that is policy working, not a crash. Implies require_transparency; a receipt failure after settlement still reports settled=true. Buyer must verify with a pinned log key and recheck the actual seller challenge immediately before signing. Preserve raw response JSON. The default 60-second freshness window starts at observation, not receipt issuance. Expiry or a changed seller challenge does not undo a settled routing fee. Default false; existing requests keep the v3 receipt path. This is not a payment authorization. Guide: https://402signal.com/developers#route-binding | |
| max_service_latency_ms | No | Drop live hits whose historical p50 latency exceeds this bound. Unknown p50 fails closed. | |
| max_candidates_to_probe | No | Requested probe cap, hard-capped at 20. | |
| max_settlement_latency_ms | No | Settlement/finality bound. Not probe RTT. Unknown fails closed. | |
| min_reputation_confidence | No | Require reputation_confidence. n_7d < 10 is low confidence. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| live | No | ||
| risk | No | Omitted or empty when none. ["payTo_changed"] whenever payTo_changed is true. | |
| payTo | No | Recipient of the selected offer as observed in the live challenge. | |
| tried | No | ||
| target | No | ||
| billing | Yes | 402Signal checking-fee outcome. Seller payment is separate. | |
| changes | No | ||
| claimed | No | Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts. | |
| payable | No | ||
| compared | No | Slim probe rows. selectable, payTo_pending, payTo_changed, risk and excluded_reason show why a live row was not eligible. excluded_reason binding_unavailable marks a skipped binding failure. | |
| observed | No | What 402Signal itself observed in the seller's live 402 challenge at verified_at (402signal_observed rows, trusted classes only). This side, not the catalog claim, is what a buyer pays. | |
| pq_trust | No | To verify the routing decision later, securely retain the complete paid /route response, especially pq_trust.transparency.receipt and pq_trust.transparency.reveal. Private replay outcomes support bounded recovery of the original response; they are not long-term evidence storage. Keep your own copy. Modified evidence fails verification against the public log. | |
| invocable | No | ||
| objective | No | ||
| readiness | No | ||
| latency_ms | No | ||
| reputation | No | Transparent components first (observed, usage, tenure, stability, source_count), then V2 reputation_score, reputation_confidence, and scoring_model_id/hash. Score is never returned without components. No public 0-100 catalog badge. Unique payer addresses are never listed. | |
| miss_reason | No | ||
| payTo_age_s | No | Seconds since the last observed recipient change for this URL, when one is recorded. | |
| stop_reason | No | ||
| verified_at | No | When the observed live challenge was taken. | |
| probed_count | No | ||
| binding_error | No | HTTP 503 when require_route_binding is true and no remaining already-probed selectable candidate could bind. Policy working, not a crash; wrapExactAuthorize reports state=binding_unavailable with keep_calling_route true. | |
| payTo_changed | No | True when the observed payTo (the live challenge at verified_at) differs from the catalog claim (claimed.payTo at claimed_at) or from the last trusted destination 402Signal itself observed for this URL. Compare claimed.payTo with observed.payTo; the observed side is the one a buyer would pay. | |
| payTo_pending | No | First unexpected rotation of the observed payTo against 402Signal's own previous trusted observation of this URL, judged on that history alone (an updated catalog claim does not clear it). Not selectable unless accept_payTo_change is true; a second independent observation of the same destination establishes it. | |
| probe_ceiling | No | ||
| schema_source | No | ||
| observed_age_s | No | Seconds since observed.observed_at. | |
| unprobed_count | No | ||
| decision_binding | No | Opt in to proof_carrying_route_v1 and a signed v4 receipt. Requires exact x402 v2 terms observed on the same HTTPS URL, method and probe body, without redirects or unresolved policy. If the ranked winner cannot bind, the router may fall through to the next already-probed selectable candidate that can; there is no unguarded settle. HTTP 503 route_binding_unavailable only when none remain bindable (a free typed miss). wrapExactAuthorize reports state=binding_unavailable with keep_calling_route true; that is policy working, not a crash. Implies require_transparency; a receipt failure after settlement still reports settled=true. Buyer must verify with a pinned log key and recheck the actual seller challenge immediately before signing. Preserve raw response JSON. The default 60-second freshness window starts at observation, not receipt issuance. Expiry or a changed seller challenge does not undo a settled routing fee. Default false; existing requests keep the v3 receipt path. This is not a payment authorization. Guide: https://402signal.com/developers#route-binding | |
| discovered_count | No | ||
| selected_payment | No | ||
| candidates_probed | No | ||
| discovery_matches | No | ||
| unmet_constraints | No | ||
| challenge_observed | No | ||
| applied_constraints | No | ||
| claimed_payTo_match | No | Whether observed.payTo equals claimed.payTo, compared per rail (case-insensitive on EVM). False on a mismatch; null when either side is unknown. Independent of payTo_pending, which judges against 402Signal's own observation history. | |
| evaluation_complete | No | ||
| candidates_considered | No | ||
| candidates_discovered | No | ||
| probe_budget_exhausted | No | ||
| unresolved_constraints | No | ||
| interpreted_constraints | No | ||
| candidate_evaluation_complete | No |