Your first call when you do not know which x402 service exists for a job: it narrows a directory of 500+ listed services to candidates. Filter by free-text query, category, network, live status, and whether the last observed 402 envelope is signable by a standard x402 client; sort by newest, uptime, cheapest, or endpoints. Returns up to 100 compact summaries a page: price in decimal USD, uptime, status, verification. Then x402_get_service for the full record.
Call this once you hold a slug and are deciding whether to commit to that service: the full record behind a directory row. Live status, uptime over 24h/7d/30d/90d, average response time, networks and settlement asset, every priced endpoint, and the assessment block. include_series=true adds 90 daily points of on-chain volume and distinct buyers. Read the units map in the response: the per-endpoint price field is atomic token units, not dollars.
Call this when you have a need in words and want one service to call rather than a list to read: it is the free ranking step between searching and paying. Pass the need as q, plus any category, network, price cap or verification requirement, and get up to 20 ranked recommendations with the basis each one placed on. Ranking is mostly per-service reliability (live status, verification, uptime, response time), x402 compliance, and price in USD, with a small (about 10%) weight on measured on-chain settlement traction that can never dominate those three. The response carries ranking_version (currently 3), need_blind_ranking (true when no q was given, so the order is global quality rather than your need), and a units map holding every scoring caveat in full: the compliance cap, the pro-quota rule for shared payout addresses, renormalization, the $10 volume floor, and the single-buyer discount. Read units before comparing scores across generations.
Call this before you send a payment, or right after a call unexpectedly failed: is this service up right now. With no slug, the directory snapshot: five status counts across 500+ services (include_services=true attaches every row). With a slug: that service's status, its 24h/7d/30d/90d uptime windows, response time, consecutive failures, daily snapshots. No money fields.
Call this when the question is about the rail rather than the service: which x402 facilitator actually settles money, and how much. Returns on-chain-verified settlement volume and transaction counts per facilitator for today (UTC), 7d, 30d and all-time, plus a verification flag ('on-chain' once volume has been observed on-chain, else 'listed'), across more than 30 facilitators. Optional daily timeseries (up to 90 days) and per-chain breakdown. Volume is decimal USD. Caveats: PER-FACILITATOR, never per-service; the *_24h fields cover today (UTC) so far, not a trailing 24 hours, and reset at 00:00 UTC, so prefer 7d.
Call this when the free signals have run out: you hold 2 to 8 finalists from x402_search_services or x402_find_best_service, their stored fields do not separate them for YOUR stated need, and choosing wrong costs more than a quarter. It buys one fresh AI assessment reasoned against your question, not a cached grade; reading an already-computed assessment stays free via x402_get_service. Price: a one-time $0.25 USDC on Base, over two calls. Call once WITHOUT payment_signature_b64 to receive the x402 payment challenge verbatim (accepts[], amount, payTo, and a base64 PAYMENT-REQUIRED header); sign accepts[0] client-side with your own wallet; call again with the SAME question and services plus payment_signature_b64 to receive the report and a base64 PAYMENT-RESPONSE settlement receipt. This server holds no keys, never signs and never settles: it only relays the challenge. Optionally add probe { slug, endpoint_path? } to have one listed service paid and called for real and its answer analyzed: the challenge is then priced at $0.25 plus that endpoint price X, and the report gains a probe_report block with a verdict and truncated extracts, never the verbatim third-party body. When live probing is not armed the probe is ignored. Caveats: read the amount to sign from accepts[0].amount, never from a fixed figure, since a probe changes it; probe fees are non-refundable whatever the verdict; if the fresh run cannot be produced the server answers before settling, so you are never charged for nothing; there is no refund. Prices are US dollars.
Call this before you trust anything you cached about a service, and right after a payment failed for no obvious reason: the monitor's log of what moved under you. Returns payTo, price and 402-schema changes observed on listed services, most recent first, in exactly three event types (payto_changed, price_changed, schema_changed). Filter with service (the slug), type, and days (1 to 365, default 90). Caveats: prices here are atomic token amounts, never dollars, and every payTo is masked by design, so the feed reports THAT the payout address changed, never the address. Free and read-only.
