402Signal

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

{
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "description": "What the caller wants routed (plain English)."
    },
    "url": {
      "type": "string",
      "description": "Optional https URL to probe instead of discovery. need or url (or both) is required."
    },
    "prefer_network": {
      "type": "string",
      "enum": [
        "base",
        "solana",
        "algorand",
        "polygon",
        "arbitrum",
        "monad",
        "worldchain",
        "xlayer",
        "bnb",
        "hyperevm",
        "ethereum",
        "optimism",
        "avalanche",
        "tempo",
        "sei",
        "celo",
        "robinhood"
      ],
      "description": "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."
    },
    "objective": {
      "type": "string",
      "enum": [
        "best",
        "cheapest",
        "fastest",
        "most_reliable",
        "lowest_total_cost",
        "fastest_settlement"
      ],
      "description": "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."
    },
    "max_amount_atomic": {
      "type": "integer",
      "minimum": 0,
      "description": "Drop live hits whose known atomic amount exceeds this bound. Unknown or cross-asset amount fails closed."
    },
    "max_price_usd": {
      "type": "number",
      "minimum": 0,
      "description": "Drop live hits whose known normalized USD exceeds this bound. Unknown USD fails closed."
    },
    "max_latency_ms": {
      "type": "integer",
      "minimum": 0,
      "description": "Compatibility alias for max_probe_latency_ms (this request's probe RTT). Unknown latency fails closed."
    },
    "max_probe_latency_ms": {
      "type": "integer",
      "minimum": 0,
      "description": "Drop live hits whose known probe RTT exceeds this bound. Not historical service/p50 latency."
    },
    "max_service_latency_ms": {
      "type": "integer",
      "minimum": 0,
      "description": "Drop live hits whose historical p50 latency exceeds this bound. Unknown p50 fails closed."
    },
    "require_invocable": {
      "type": "boolean",
      "description": "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."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "base",
          "solana",
          "algorand",
          "polygon",
          "arbitrum",
          "monad",
          "worldchain",
          "xlayer",
          "bnb",
          "hyperevm",
          "ethereum",
          "optimism",
          "avalanche",
          "tempo",
          "sei",
          "celo",
          "robinhood"
        ]
      },
      "description": "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."
    },
    "min_observations": {
      "type": "integer",
      "minimum": 0,
      "description": "Require history n_7d at least this large. Unknown or smaller fails closed."
    },
    "min_observed_success": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Require observed success_7d when n_7d >= 3. Unknown fails closed."
    },
    "min_reputation_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Require V1 reputation_score. Unknown fails closed. Never guessed from vague NL."
    },
    "min_reputation_confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Require reputation_confidence. n_7d < 10 is low confidence."
    },
    "max_total_cost_usd": {
      "type": "number",
      "minimum": 0,
      "description": "Merchant price plus known fees. Unknown fee fails closed."
    },
    "max_settlement_latency_ms": {
      "type": "integer",
      "minimum": 0,
      "description": "Settlement/finality bound. Not probe RTT. Unknown fails closed."
    },
    "search_depth": {
      "type": "string",
      "enum": [
        "standard",
        "thorough"
      ],
      "description": "standard: first 3 then expand 2-4 (typical cap 7). thorough may expand further. Hard server ceiling is 20."
    },
    "max_candidates_to_probe": {
      "type": "integer",
      "minimum": 1,
      "description": "Requested probe cap, hard-capped at 20."
    },
    "policy": {
      "type": "string",
      "description": "Natural-language constraints compiled into structured values. Unresolved phrases are returned, never guessed."
    },
    "accept_payTo_change": {
      "type": "boolean",
      "description": "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."
    },
    "require_route_binding": {
      "type": "boolean",
      "description": "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"
    },
    "require_transparency": {
      "type": "boolean",
      "description": "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."
    }
  },
  "anyOf": [
    {
      "required": [
        "need"
      ]
    },
    {
      "required": [
        "url"
      ]
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "live": {
      "type": "boolean"
    },
    "url": {
      "type": [
        "string",
        "null"
      ]
    },
    "challenge_observed": {
      "type": "boolean"
    },
    "payable": {
      "type": "boolean"
    },
    "invocable": {
      "type": "boolean"
    },
    "selected_payment": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "rail": {
          "type": [
            "string",
            "null"
          ]
        },
        "network": {
          "type": [
            "string",
            "null"
          ]
        },
        "asset": {
          "type": [
            "string",
            "null"
          ]
        },
        "amount_atomic": {
          "type": [
            "integer",
            "null"
          ]
        },
        "display_amount": {
          "type": [
            "string",
            "null"
          ]
        },
        "normalized_usd": {
          "type": [
            "number",
            "null"
          ]
        },
        "payTo": {
          "type": [
            "string",
            "null"
          ]
        },
        "facilitator": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "billing": {
      "type": "object",
      "description": "402Signal checking-fee outcome. Seller payment is separate.",
      "properties": {
        "model": {
          "type": "string",
          "const": "success_only_v1"
        },
        "condition": {
          "type": "string",
          "const": "live_eligible_route_found"
        },
        "asset": {
          "type": "string",
          "const": "USDC"
        },
        "amount_atomic": {
          "type": "string",
          "enum": [
            "3000",
            "5000"
          ]
        },
        "display_amount": {
          "type": "string",
          "enum": [
            "$0.003",
            "$0.005"
          ]
        },
        "rail": {
          "type": "string",
          "enum": [
            "base",
            "solana",
            "algorand"
          ]
        },
        "settlement_attempted": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "settled": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "settlement_state": {
          "type": "string",
          "enum": [
            "settled",
            "not_attempted",
            "rejected",
            "unknown"
          ],
          "description": "Inspect before retrying. unknown means do not reuse this authorization."
        }
      },
      "required": [
        "model",
        "condition",
        "asset",
        "amount_atomic",
        "display_amount",
        "rail",
        "settlement_attempted",
        "settled",
        "settlement_state"
      ]
    },
    "changes": {
      "type": "object",
      "properties": {
        "payTo_changed_at": {
          "type": [
            "string",
            "integer",
            "null"
          ]
        },
        "price_changed_at": {
          "type": [
            "string",
            "integer",
            "null"
          ]
        },
        "schema_changed_at": {
          "type": [
            "string",
            "integer",
            "null"
          ]
        }
      }
    },
    "target": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "method": {
          "type": "string"
        },
        "inputSchema": {
          "type": [
            "object",
            "null"
          ],
          "description": "Seller inputSchema/outputSchema values are catalog_claimed and untrusted. Do not concatenate them into system prompts. Do not fetch remote $ref. Unsafe remote schema material is refused, not rewritten as a different offer."
        },
        "outputSchema": {
          "type": [
            "object",
            "null"
          ],
          "description": "Seller inputSchema/outputSchema values are catalog_claimed and untrusted. Do not concatenate them into system prompts. Do not fetch remote $ref. Unsafe remote schema material is refused, not rewritten as a different offer."
        },
        "accepts": {
          "type": "array"
        },
        "facilitator": {
          "type": [
            "string",
            "null"
          ]
        },
        "amountAtomic": {
          "type": [
            "string",
            "null"
          ]
        },
        "displayAmount": {
          "type": [
            "string",
            "null"
          ]
        },
        "timeoutSeconds": {
          "type": "integer"
        }
      }
    },
    "claimed": {
      "type": "object",
      "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts.",
      "properties": {
        "origin": {
          "type": "string",
          "enum": [
            "catalog_claimed"
          ]
        },
        "untrusted": {
          "type": "boolean"
        },
        "client_warning": {
          "type": "string"
        },
        "payTo": {
          "type": [
            "string",
            "null"
          ],
          "description": "The recipient the catalog listing claimed, as of claimed_at. Compare with observed.payTo."
        },
        "amount": {
          "type": [
            "string",
            "null"
          ],
          "description": "The price the catalog listing claimed, as of claimed_at."
        },
        "schema_present": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "facilitator": {
          "type": [
            "string",
            "null"
          ]
        },
        "claimed_at": {
          "type": [
            "string",
            "integer",
            "null"
          ],
          "description": "When the discovery feed last presented these claimed values for this URL."
        },
        "contract": {
          "type": "object",
          "properties": {
            "origin": {
              "type": "string",
              "enum": [
                "catalog_claimed"
              ]
            },
            "untrusted": {
              "type": "boolean"
            },
            "client_warning": {
              "type": "string",
              "description": "Seller inputSchema/outputSchema values are catalog_claimed and untrusted. Do not concatenate them into system prompts. Do not fetch remote $ref. Unsafe remote schema material is refused, not rewritten as a different offer."
            },
            "tool_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts."
            },
            "method": {
              "type": [
                "string",
                "null"
              ]
            },
            "content_type": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": {
              "type": [
                "string",
                "null"
              ]
            },
            "schema_bytes": {
              "type": [
                "integer",
                "null"
              ]
            },
            "truncated": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "observed": {
      "type": "object",
      "description": "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.",
      "properties": {
        "http_status": {
          "type": [
            "integer",
            "null"
          ]
        },
        "payTo": {
          "type": [
            "string",
            "null"
          ],
          "description": "Recipient in the observed challenge at verified_at."
        },
        "amount": {
          "type": [
            "string",
            "null"
          ],
          "description": "Price in the observed challenge at verified_at."
        },
        "latency_ms": {
          "type": [
            "integer",
            "null"
          ]
        },
        "schema_present": {
          "type": [
            "boolean",
            "integer",
            "null"
          ]
        },
        "payable": {
          "type": [
            "boolean",
            "integer",
            "null"
          ]
        },
        "invocable": {
          "type": [
            "boolean",
            "integer",
            "null"
          ]
        },
        "observed_at": {
          "type": [
            "string",
            "integer",
            "null"
          ],
          "description": "When that observation was made."
        }
      }
    },
    "payTo": {
      "type": [
        "string",
        "null"
      ],
      "description": "Recipient of the selected offer as observed in the live challenge."
    },
    "payTo_changed": {
      "type": "boolean",
      "description": "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": {
      "type": "boolean",
      "description": "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."
    },
    "claimed_payTo_match": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "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."
    },
    "risk": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Omitted or empty when none. [\"payTo_changed\"] whenever payTo_changed is true."
    },
    "payTo_age_s": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Seconds since the last observed recipient change for this URL, when one is recorded."
    },
    "observed_age_s": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Seconds since observed.observed_at."
    },
    "verified_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the observed live challenge was taken."
    },
    "readiness": {
      "type": "string",
      "enum": [
        "discovered",
        "payable",
        "invocable",
        "recently_verified"
      ]
    },
    "miss_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "no_candidates",
        "no_402_envelope",
        "no_payto",
        "reachable_200",
        "probe_timeout",
        "quote_expired",
        "invalid_need",
        "upstream_5xx",
        "ssrf",
        "unlisted",
        "no_input_schema",
        "constraints_unmet",
        "binding_unavailable",
        "probe_budget_exhausted",
        "probe_limit_reached",
        "unsafe_to_probe",
        "settlement_unknown",
        "authorization_used",
        "probe_capacity",
        "window_spent",
        "fingerprint_miss",
        "scheme_mismatch",
        "network_mismatch",
        "invalid_session_shape",
        "mandate_mismatch",
        "unsupported_hop_field",
        null
      ]
    },
    "tried": {
      "type": "integer"
    },
    "discovery_matches": {
      "type": "integer"
    },
    "candidates_discovered": {
      "type": "integer"
    },
    "candidates_considered": {
      "type": "integer"
    },
    "candidates_probed": {
      "type": "integer"
    },
    "probe_ceiling": {
      "type": "integer"
    },
    "probe_budget_exhausted": {
      "type": "boolean"
    },
    "candidate_evaluation_complete": {
      "type": "boolean"
    },
    "evaluation_complete": {
      "type": "boolean"
    },
    "discovered_count": {
      "type": "integer"
    },
    "probed_count": {
      "type": "integer"
    },
    "unprobed_count": {
      "type": "integer"
    },
    "interpreted_constraints": {
      "type": "object"
    },
    "applied_constraints": {
      "type": "object"
    },
    "unmet_constraints": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "unresolved_constraints": {
      "type": "array"
    },
    "stop_reason": {
      "type": "string",
      "enum": [
        "probe_capacity",
        "winner_selected",
        "candidate_set_exhausted",
        "probe_limit_reached",
        "probe_budget_exhausted",
        "constraints_unmet"
      ]
    },
    "latency_ms": {
      "type": [
        "integer",
        "null"
      ]
    },
    "schema_source": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "envelope",
        "catalog",
        "bazaar",
        null
      ]
    },
    "reputation": {
      "type": "object",
      "description": "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.",
      "properties": {
        "stability": {
          "type": "object",
          "description": "Observed changes to this URL's terms (402signal_observed, not catalog claims): a change is a live challenge whose recipient, price, schema or rail differed from the previous trusted observation of the same URL.",
          "properties": {
            "payTo_changes": {
              "type": "object",
              "properties": {
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Observed changes in the window; null when unknown."
                },
                "changed_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "RFC3339 time of the last observed change, or null."
                }
              }
            },
            "price_changes": {
              "type": "object",
              "properties": {
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Observed changes in the window; null when unknown."
                },
                "changed_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "RFC3339 time of the last observed change, or null."
                }
              }
            },
            "schema_changes": {
              "type": "object",
              "properties": {
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Observed changes in the window; null when unknown."
                },
                "changed_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "RFC3339 time of the last observed change, or null."
                }
              }
            },
            "rail_changes": {
              "type": "object",
              "properties": {
                "count": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Observed changes in the window; null when unknown."
                },
                "changed_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "RFC3339 time of the last observed change, or null."
                }
              }
            }
          }
        }
      }
    },
    "objective": {
      "type": "string",
      "enum": [
        "best",
        "cheapest",
        "fastest",
        "most_reliable",
        "lowest_total_cost",
        "fastest_settlement"
      ]
    },
    "decision_binding": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "model",
        "observed_at",
        "expires_at",
        "request",
        "quote_sha256",
        "selected_index"
      ],
      "properties": {
        "model": {
          "type": "string",
          "const": "proof_carrying_route_v1"
        },
        "observed_at": {
          "type": "integer",
          "minimum": 0
        },
        "expires_at": {
          "type": "integer",
          "minimum": 1
        },
        "quote_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "selected_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 31
        },
        "request": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "url",
            "method",
            "body_sha256"
          ],
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            },
            "method": {
              "type": "string",
              "enum": [
                "GET",
                "POST"
              ]
            },
            "body_sha256": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        }
      },
      "description": "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"
    },
    "binding_error": {
      "type": "string",
      "enum": [
        "route_binding_unavailable"
      ],
      "description": "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."
    },
    "pq_trust": {
      "type": "object",
      "description": "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.",
      "properties": {
        "transparency": {
          "type": "object",
          "description": "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.",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "queued",
                "logged_uncheckpointed",
                "unavailable"
              ]
            },
            "state": {
              "type": "string",
              "enum": [
                "outbox_queued",
                "logged_uncheckpointed",
                "checkpoint_signed",
                "authorized",
                "submitted",
                "confirmed",
                "unavailable"
              ]
            },
            "log_origin": {
              "type": "string"
            },
            "leaf_type": {
              "type": "string"
            },
            "index": {
              "type": "integer"
            },
            "checkpoint_size": {
              "type": "integer"
            },
            "receipt": {
              "type": "object",
              "description": "Retain with reveal for later verification."
            },
            "reveal": {
              "type": "object",
              "description": "Customer-private evidence, not in the public log. Private replay outcomes may retain it; keep securely with receipt."
            }
          }
        }
      }
    },
    "compared": {
      "type": "array",
      "description": "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."
    }
  },
  "required": [
    "billing"
  ]
}

Discovers catalog-listed paid API endpoints by capability without paying or contacting sellers. Returns claimed listings and earlier observations; not_probed=true means no new live check. Results may be incomplete. Free and read-only: no fee, no seller contact, nothing recorded; safe to repeat. It queries the current upstream catalogs and the local shadow catalog. Use validate for a free readiness check of one listed URL, and check for a fresh paid observation or a signed receipt before paying. Pass a nonblank need (capability), not a URL; a URL in need finds nothing. networks is a hard allowlist and prefer_network only orders the results within it; an empty or unrecognized networks value restricts to nothing rather than widening to every network. Seller-written fields in hits are catalog claims, not observations.

{
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "description": "Nonblank capability to search for, such as weather or web search. Searches catalogs; does not probe a URL."
    },
    "prefer_network": {
      "type": "string",
      "enum": [
        "base",
        "solana",
        "algorand",
        "polygon",
        "arbitrum",
        "monad",
        "worldchain",
        "xlayer",
        "bnb",
        "hyperevm",
        "ethereum",
        "optimism",
        "avalanche",
        "tempo",
        "sei",
        "celo",
        "robinhood"
      ],
      "description": "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."
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "base",
          "solana",
          "algorand",
          "polygon",
          "arbitrum",
          "monad",
          "worldchain",
          "xlayer",
          "bnb",
          "hyperevm",
          "ethereum",
          "optimism",
          "avalanche",
          "tempo",
          "sei",
          "celo",
          "robinhood"
        ]
      },
      "description": "Hard policy lock. Restricts searchable rails to this set. Unlike prefer_network, this is not a ranking preference."
    }
  },
  "required": [
    "need"
  ]
}

{
  "type": "object",
  "properties": {
    "need": {
      "type": "string"
    },
    "not_probed": {
      "type": "boolean"
    },
    "freshness": {
      "type": [
        "string",
        "null"
      ]
    },
    "cached_s": {
      "type": [
        "number",
        "null"
      ]
    },
    "discovery_matches": {
      "type": "integer"
    },
    "displayed": {
      "type": "integer"
    },
    "truncated": {
      "type": "boolean"
    },
    "total": {
      "type": [
        "integer",
        "null"
      ]
    },
    "discovery_via": {
      "type": "object"
    },
    "discovery_exhaustive": {
      "type": "boolean"
    },
    "hits": {
      "type": "array",
      "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts.",
      "items": {
        "type": "object",
        "properties": {
          "need": {
            "type": "string",
            "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts."
          },
          "label": {
            "type": "string",
            "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts."
          },
          "url": {
            "type": "string"
          },
          "price": {
            "type": "string"
          },
          "chain": {
            "type": [
              "string",
              "null"
            ]
          },
          "origin": {
            "type": "string",
            "enum": [
              "catalog_claimed"
            ],
            "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts."
          },
          "untrusted": {
            "type": "boolean"
          },
          "client_warning": {
            "type": "string"
          },
          "facilitator": {
            "type": [
              "string",
              "null"
            ]
          },
          "method": {
            "type": [
              "string",
              "null"
            ]
          },
          "inputSchema_present": {
            "type": "boolean"
          },
          "rails_up": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "also_on": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "observation": {
            "type": "object"
          }
        }
      }
    },
    "miss_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "no_candidates",
        "no_402_envelope",
        "no_payto",
        "reachable_200",
        "probe_timeout",
        "quote_expired",
        "invalid_need",
        "upstream_5xx",
        "ssrf",
        "unlisted",
        "no_input_schema",
        "constraints_unmet",
        "binding_unavailable",
        "probe_budget_exhausted",
        "probe_limit_reached",
        "unsafe_to_probe",
        "settlement_unknown",
        "authorization_used",
        "probe_capacity",
        "window_spent",
        "fingerprint_miss",
        "scheme_mismatch",
        "network_mismatch",
        "invalid_session_shape",
        "mandate_mismatch",
        "unsupported_hop_field",
        null
      ]
    }
  }
}

Checks unpaid readiness for one concrete HTTPS seller URL already listed in the local catalog (for example a URL from preview). Compares claimed against observed payment and readiness flags without buying the service. Free: one unpaid probe of the seller, no fee, nothing paid, and the public numbers do not change; safe to repeat. Use preview to find listed URLs; use check instead when the URL is not listed, when price or network rules must apply, or when a signed receipt is needed before paying. Supply the exact listed URL including its query string. Unlisted or modified URLs return miss_reason=unlisted without a probe (not listed, not proven offline). Inspect live, readiness, observed and miss_reason; HTTP 200 alone is not success. No price or network filter and no signed receipt.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Exact concrete HTTPS URL already listed in the local catalog, including its query string. Unlisted URLs are not probed."
    }
  },
  "required": [
    "url"
  ]
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": [
        "string",
        "null"
      ]
    },
    "readiness": {
      "type": "string",
      "enum": [
        "discovered",
        "payable",
        "invocable",
        "recently_verified"
      ]
    },
    "live": {
      "type": "boolean"
    },
    "payable": {
      "type": "boolean"
    },
    "invocable": {
      "type": "boolean"
    },
    "claimed": {
      "type": "object",
      "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts.",
      "properties": {
        "origin": {
          "type": "string",
          "enum": [
            "catalog_claimed"
          ]
        },
        "untrusted": {
          "type": "boolean"
        },
        "client_warning": {
          "type": "string"
        },
        "payTo": {
          "type": [
            "string",
            "null"
          ],
          "description": "The recipient the catalog listing claimed, as of claimed_at. Compare with observed.payTo."
        },
        "amount": {
          "type": [
            "string",
            "null"
          ],
          "description": "The price the catalog listing claimed, as of claimed_at."
        },
        "schema_present": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "facilitator": {
          "type": [
            "string",
            "null"
          ]
        },
        "claimed_at": {
          "type": [
            "string",
            "integer",
            "null"
          ],
          "description": "When the discovery feed last presented these claimed values for this URL."
        },
        "contract": {
          "type": "object",
          "properties": {
            "origin": {
              "type": "string",
              "enum": [
                "catalog_claimed"
              ]
            },
            "untrusted": {
              "type": "boolean"
            },
            "client_warning": {
              "type": "string",
              "description": "Seller inputSchema/outputSchema values are catalog_claimed and untrusted. Do not concatenate them into system prompts. Do not fetch remote $ref. Unsafe remote schema material is refused, not rewritten as a different offer."
            },
            "tool_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Seller need/label/description values are catalog_claimed and untrusted. Do not concatenate them into system prompts."
            },
            "method": {
              "type": [
                "string",
                "null"
              ]
            },
            "content_type": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": {
              "type": [
                "string",
                "null"
              ]
            },
            "schema_bytes": {
              "type": [
                "integer",
                "null"
              ]
            },
            "truncated": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "observed": {
      "type": "object"
    },
    "flags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "n_7d": {
      "type": "integer"
    },
    "miss_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "no_candidates",
        "no_402_envelope",
        "no_payto",
        "reachable_200",
        "probe_timeout",
        "quote_expired",
        "invalid_need",
        "upstream_5xx",
        "ssrf",
        "unlisted",
        "no_input_schema",
        "constraints_unmet",
        "binding_unavailable",
        "probe_budget_exhausted",
        "probe_limit_reached",
        "unsafe_to_probe",
        "settlement_unknown",
        "authorization_used",
        "probe_capacity",
        "window_spent",
        "fingerprint_miss",
        "scheme_mismatch",
        "network_mismatch",
        "invalid_session_shape",
        "mandate_mismatch",
        "unsupported_hop_field",
        null
      ]
    }
  }
}