{"openapi":"3.1.0","info":{"title":"x402 Trust: trust & reliability data for the x402 ecosystem","version":"2.0.0","description":"Trust & reliability scores for x402 endpoints. Continuous 24/7 monitoring of every publicly listed x402 service: uptime probes, 402-envelope spec compliance, advertised price history, and real on-chain USDC settlement volume per payTo address. Deterministic, auditable scoring: know before you pay. Try it free at /v1/x402-trust-preview; free top-25 leaderboard at /trust/leaderboard.","x-guidance":"We monitor every publicly listed x402 endpoint 24/7: uptime probes, 402-envelope compliance, advertised price history, and REAL on-chain USDC settlement volume per payTo address. Buy a trust score before you pay an unknown endpoint. Payment: USDC EIP-3009 on Base mainnet (eip155:8453) via the x402 PAYMENT-SIGNATURE header. Free tier: GET /v1/x402-trust-preview (full sample reports for 3 fixed endpoints) and GET /trust/leaderboard.","contact":{"name":"x402 Trust","url":"https://x402-trust.com"}},"servers":[{"url":"https://x402-trust.com"}],"paths":{"/v1/x402-trust-preview":{"get":{"summary":"FREE trust preview — full sample reports, see before you pay","description":"Free, no-payment SHOWCASE of POST /v1/x402-trust. Returns the COMPLETE paid-grade trust report (every field: exact score, scoreRange, full breakdown, advertised price, on-chain settlement proof, all flags) for THREE endpoints you do NOT get to choose — the best-scored, the population median, and the worst-scored — so you see exactly what the paid output looks like across the whole quality range. To score YOUR OWN endpoint you must pay POST /v1/x402-trust. Takes no parameters.","responses":{"200":{"description":"Trust preview (3 full sample reports: best/median/worst)","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"FREE trust preview — full sample reports (POST)","description":"Same as GET /v1/x402-trust-preview. Free, no payment, no parameters — returns the same three full sample reports (best/median/worst).","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Trust preview","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/x402-trust":{"post":{"summary":"Trust score for any x402 endpoint (cataloged or not)","description":"Deterministic trust score (0-100, graded A-F) computed from our observation history: 30d probe uptime, 402-envelope spec compliance, latency, observed age, on-chain USDC settlement activity to the endpoint's payTo, and price stability. Returns the full component breakdown + machine-readable flags so you can audit the math. No LLM involved. Uncataloged endpoints are live-probed on first query and auto-adopted into the monitored catalog (first-contact flag, low confidence -- history accumulates from there).","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","description":"Full x402 resource URL (https://...) as listed in discovery."}},"required":["resource"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"$schema":{"type":"string","description":"Canonical URL of this response's JSON Schema (see /schemas/)."},"schemaVersion":{"type":"string","description":"Semver of this response schema."},"schemaType":{"type":"string","description":"Discriminator naming this schema (x402-trust)."},"resource":{"type":"string","description":"Echoed resource URL."},"serviceName":{"type":"string","description":"Provider-advertised service name (unverified)."},"description":{"type":"string","description":"Provider-advertised endpoint description (unverified free text)."},"score":{"type":"number","description":"0-100 trust score."},"grade":{"type":"string","description":"A/B/C/D/F."},"confidence":{"type":"number","description":"0-1, scales with observation count."},"breakdown":{"type":"object","description":"Per-component subscores (uptime, compliance, latency, age, activity, stability)."},"flags":{"type":"object","description":"Machine-readable issue slugs."},"stats":{"type":"object","description":"Raw 30d stats the score was computed from."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/x402-history":{"post":{"summary":"Observation history for any listed x402 endpoint","description":"Raw time-series from our monitoring database: discovery snapshots (listed/delisted/relisted, advertised price changes, payTo changes) and probe results (uptime, latency, quoted amount) for the requested window. This is the data nobody can backfill — we were watching, you weren't.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","description":"Full x402 resource URL (https://...) as listed in discovery."},"days":{"type":"number","description":"Lookback window in days (1-90, default 30)."}},"required":["resource"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment Required"}}}},"/v1/similar":{"post":{"summary":"Find better-scored alternatives to an x402 endpoint","description":"Given a resource URL, returns the top semantically-similar x402 endpoints (matched on advertised purpose via description embeddings) that currently OUT-SCORE it on our deterministic trust score. For routing an agent away from a mediocre endpoint toward a more reliable, better-settled one serving the same function. Same-host siblings and 'avoid'-flagged endpoints are excluded. Empty list is a valid answer when nothing beats the subject. Similarity is cosine over description embeddings and is independent of latency/geography.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","description":"Full x402 resource URL (https://...) as listed in discovery."},"limit":{"type":"number","description":"Max alternatives to return (1-25, default 5)."},"minScoreDelta":{"type":"number","description":"Minimum trust-score advantage an alternative must have over the subject (default 5)."}},"required":["resource"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","description":"Echoed subject resource URL."},"subject":{"type":"object","description":"Subject's own score/grade + observation status."},"count":{"type":"number","description":"Number of alternatives returned."},"alternatives":{"type":"object","description":"Ranked array: resource, score, grade, recommendation, similarity, amountUsd, network, endpointPage."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/semantic-search":{"post":{"summary":"Semantic search over the x402 catalog (free-text query)","description":"Given a free-text query (e.g. \"weather forecast\", \"image generation\"), returns the up to 25 semantically closest endpoints in the monitored catalog. Ranking is deterministic: cosine similarity bucketed to whole percentage points first (80.3% and 80.5% tie), then trust score, then described-before-undescribed, then endpoint id. Matches below a 0.5 cosine-similarity floor are dropped, so a query can return fewer than the requested limit. Endpoints that advertise no description are matched via their service name and URL path tokens instead: no fixed malus, only the tiebreak loss at equal bucket + score (the shorter fallback text typically yields lower similarity). Each match carries resource, score, grade, similarity (0-1), description (when present) and a free endpointPage URL. Discovery only: no verdict, recommendation or flag detail (POST /v1/x402-trust carries those per endpoint). The query is embedded with the same model as the catalog, so phrase the capability you need.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Free-text search query (1-500 chars). Describe the capability you need in plain words."},"limit":{"type":"number","description":"Max matches to return (1-25, default 25)."}},"required":["query"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Echoed query string."},"count":{"type":"number","description":"Number of matches returned."},"matches":{"type":"object","description":"Ranked array: id, resource, score, grade, similarity, description, endpointPage. score/grade are null when unscored."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/watch-endpoint-30d":{"post":{"summary":"Watch one x402 endpoint for 30 days (change + liveness alerts)","description":"Monitor ONE listed x402 endpoint for 30 days and get alerted on changes that break agents: payTo changes (critical — possible takeover/rug), price changes, asset/network changes, 402-spec regressions, delisting, and liveness (down/recovered). Account-free: pay once, receive a ONE-TIME bearer secret + poll URL (only the hash is stored). Push to multiple signed HTTPS webhooks and/or Slack/Discord incoming webhooks (up to 5 each). Any webhook_url(s)/slack_url(s) is connection-tested BEFORE payment; unreachable URLs are rejected with notCharged:true so you can retry with a corrected URL. Edit URLs / sensitivity / events or cancel early for free via PATCH/DELETE /v1/watch/{id} (bearer-authed). Poll the append-only event log at GET /v1/watch/{id}/events?since={cursor}.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.200000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Full x402 resource URL (https://...) as listed in discovery."},"events":{"type":"array","description":"Optional event types to subscribe to (default all): payto_change, price_change, asset_network_change, spec_regression, delisting, liveness_down, liveness_recovered."},"liveness_sensitivity_n":{"type":"number","description":"Consecutive missed probes before a liveness_down is surfaced (1=paranoid … 10=relaxed; default 2)."},"delivery":{"type":"object","description":"Optional push delivery { webhook_url(s), slack_url(s) } (https public hosts, max 5 each). Each accepts a single URL string or an array. webhook_url(s) = signed HTTPS webhook; verify `x-signature` = 'sha256=' + HMAC-SHA256(body) keyed by hex(sha256(secret)) (NOT raw secret). slack_url(s) = Slack or Discord incoming webhook. All URLs are connection-tested before you're charged. Polling is always available."}},"required":["endpoint"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"watch_id":{"type":"string","description":"Opaque watch id (used in the poll/renew/edit/cancel URLs)."},"secret":{"type":"string","description":"One-time bearer secret (wsk_…); only its hash is stored. Store it now."},"poll_url":{"type":"string","description":"GET this with Authorization: Bearer <secret> to read events."},"renew_url":{"type":"string","description":"POST here with payment to extend the watch; the secret stays the same."},"edit_url":{"type":"string","description":"PATCH here (bearer-authed, free) to change delivery URLs/sensitivity/events."},"cancel_url":{"type":"string","description":"DELETE here (bearer-authed, free) to cancel the watch early."},"expires_at":{"type":"number","description":"Unix ms when the watch expires (renew to extend)."},"watched":{"type":"object","description":"The endpoint(s) covered by this watch."},"probe_interval_sec":{"type":"number","description":"Elevated probe cadence while watched."},"subscribed_events":{"type":"array","description":"Event types the watch is subscribed to, or 'all'."},"liveness_sensitivity_n":{"type":"number","description":"Consecutive misses before liveness_down is surfaced to you."},"delivery":{"type":"object","description":"Enabled push channels + connection_test results (poll is always true)."},"next_steps":{"type":"array","description":"Machine-readable integration steps for agents/humans."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/watch/{id}/events":{"get":{"summary":"Poll a watch's event log (free, bearer-authed)","description":"Returns two streams: `events` (endpoint changes, filtered by the watch's subscribed events + liveness sensitivity) and `watch_events` (lifecycle feedback: created/edited/cancelled/renewed/expiring/expired). Auth: `Authorization: Bearer <secret>` (never in the URL). Nothing is lost between polls (append-only + monotonic cursors). Advance `since` with `next_cursor` and `watch_since` with `watch_events_cursor`. Free — you already paid to create the watch.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"watch_id."},{"name":"since","in":"query","required":false,"schema":{"type":"integer"},"description":"Endpoint-event cursor (next_cursor). Omit or 0 for all."},{"name":"watch_since","in":"query","required":false,"schema":{"type":"integer"},"description":"Lifecycle-event cursor (watch_events_cursor). Omit or 0 for all."}],"responses":{"200":{"description":"events + next_cursor + watch_events + watch_events_cursor + watch_expires_at","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing/invalid bearer secret"}}}},"/v1/watch/{id}":{"patch":{"summary":"Edit a watch (free, bearer-authed)","description":"Change the webhook/Slack URLs, liveness sensitivity, or subscribed events of an active watch. Auth: `Authorization: Bearer <secret>`. Newly-added URLs are connection-tested before the change is persisted; if any new URL fails, the existing config is left unchanged and the response reports per-URL results. Delivery fields are full-replace per channel (omit to leave that channel unchanged). Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"watch_id."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","description":"Optional event types to subscribe to (default all)."},"liveness_sensitivity_n":{"type":"integer","description":"1=paranoid … 10=relaxed; default 2."},"delivery":{"type":"object","description":"{ webhook_url(s), slack_url(s) } — full replace per channel; max 5 each."}}}}}},"responses":{"200":{"description":"Updated watch view","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation or connection-test failure"},"401":{"description":"Missing/invalid bearer secret"},"409":{"description":"Watch is not active"}}},"delete":{"summary":"Cancel a watch early (free, bearer-authed)","description":"Soft-cancel the watch immediately. Endpoint probing drops back to normal cadence as soon as no active watches cover the endpoint. Auth: `Authorization: Bearer <secret>`. Free. Idempotent.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"watch_id."}],"responses":{"200":{"description":"Watch cancelled (or already cancelled)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing/invalid bearer secret"}}}},"/v1/watch/{id}/renew":{"post":{"summary":"Renew a watch 30 more days (same key)","description":"Extend an existing watch by 30 days. The bearer secret is UNCHANGED (no re-onboarding) and expires_at is stretched from the later of now / current expiry, so renewing early adds time rather than truncating.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.200000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"watch_id":{"type":"string","description":"Echoed watch id."},"expires_at":{"type":"number","description":"New expiry (Unix ms)."},"key_unchanged":{"type":"boolean","description":"Always true — the secret is not rotated."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/x402-trust-bulk-10":{"post":{"summary":"Bulk trust score for up to 10 endpoints","description":"Score up to 10 x402 endpoints in one call. Every found result carries the FULL trust report — identical to POST /v1/x402-trust (score, grade, scoreRange, recommendation, confidence breakdown, component/subscore breakdown, explanations, flags + flagsDetailed, advertised price, 30-day on-chain stats) — served from cached snapshots. No live re-probe — this is the scale product; for a fresh live probe use /v1/x402-trust. Resources not in our observation set return `found:false`; if NONE of the supplied resources are tracked the request is rejected with 400 `notCharged:true` and you pay nothing. Price: $0.045000 per call.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.045000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","description":"List of full x402 resource URLs. Max 10; fewer allowed; duplicates ignored."}},"required":["resources"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"integer","description":"Unix ms when the response was generated."},"tier":{"type":"integer","description":"Tier size (max endpoints)."},"requested":{"type":"integer","description":"Number of unique resources scored."},"results":{"type":"array","description":"One result per requested resource, in request order. Each found:true row is the full trust report (same fields as POST /v1/x402-trust: score, grade, scoreRange, recommendation, confidenceDetail, breakdown, subscores, explanations, flags, flagsDetailed, advertised, stats) plus the bulk provenance fields (found, endpoint_id, probes_30d, probed_at, computed_at, recomputed)."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/x402-trust-bulk-50":{"post":{"summary":"Bulk trust score for up to 50 endpoints","description":"Score up to 50 x402 endpoints in one call. Every found result carries the FULL trust report — identical to POST /v1/x402-trust (score, grade, scoreRange, recommendation, confidence breakdown, component/subscore breakdown, explanations, flags + flagsDetailed, advertised price, 30-day on-chain stats) — served from cached snapshots. No live re-probe — this is the scale product; for a fresh live probe use /v1/x402-trust. Resources not in our observation set return `found:false`; if NONE of the supplied resources are tracked the request is rejected with 400 `notCharged:true` and you pay nothing. Price: $0.200000 per call.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.200000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","description":"List of full x402 resource URLs. Max 50; fewer allowed; duplicates ignored."}},"required":["resources"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"integer","description":"Unix ms when the response was generated."},"tier":{"type":"integer","description":"Tier size (max endpoints)."},"requested":{"type":"integer","description":"Number of unique resources scored."},"results":{"type":"array","description":"One result per requested resource, in request order. Each found:true row is the full trust report (same fields as POST /v1/x402-trust: score, grade, scoreRange, recommendation, confidenceDetail, breakdown, subscores, explanations, flags, flagsDetailed, advertised, stats) plus the bulk provenance fields (found, endpoint_id, probes_30d, probed_at, computed_at, recomputed)."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/x402-trust-bulk-100":{"post":{"summary":"Bulk trust score for up to 100 endpoints","description":"Score up to 100 x402 endpoints in one call. Every found result carries the FULL trust report — identical to POST /v1/x402-trust (score, grade, scoreRange, recommendation, confidence breakdown, component/subscore breakdown, explanations, flags + flagsDetailed, advertised price, 30-day on-chain stats) — served from cached snapshots. No live re-probe — this is the scale product; for a fresh live probe use /v1/x402-trust. Resources not in our observation set return `found:false`; if NONE of the supplied resources are tracked the request is rejected with 400 `notCharged:true` and you pay nothing. Price: $0.325000 per call.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.325000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","description":"List of full x402 resource URLs. Max 100; fewer allowed; duplicates ignored."}},"required":["resources"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"integer","description":"Unix ms when the response was generated."},"tier":{"type":"integer","description":"Tier size (max endpoints)."},"requested":{"type":"integer","description":"Number of unique resources scored."},"results":{"type":"array","description":"One result per requested resource, in request order. Each found:true row is the full trust report (same fields as POST /v1/x402-trust: score, grade, scoreRange, recommendation, confidenceDetail, breakdown, subscores, explanations, flags, flagsDetailed, advertised, stats) plus the bulk provenance fields (found, endpoint_id, probes_30d, probed_at, computed_at, recomputed)."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/x402-trust-bulk-200":{"post":{"summary":"Bulk trust score for up to 200 endpoints","description":"Score up to 200 x402 endpoints in one call. Every found result carries the FULL trust report — identical to POST /v1/x402-trust (score, grade, scoreRange, recommendation, confidence breakdown, component/subscore breakdown, explanations, flags + flagsDetailed, advertised price, 30-day on-chain stats) — served from cached snapshots. No live re-probe — this is the scale product; for a fresh live probe use /v1/x402-trust. Resources not in our observation set return `found:false`; if NONE of the supplied resources are tracked the request is rejected with 400 `notCharged:true` and you pay nothing. Price: $0.400000 per call.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.400000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","description":"List of full x402 resource URLs. Max 200; fewer allowed; duplicates ignored."}},"required":["resources"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"integer","description":"Unix ms when the response was generated."},"tier":{"type":"integer","description":"Tier size (max endpoints)."},"requested":{"type":"integer","description":"Number of unique resources scored."},"results":{"type":"array","description":"One result per requested resource, in request order. Each found:true row is the full trust report (same fields as POST /v1/x402-trust: score, grade, scoreRange, recommendation, confidenceDetail, breakdown, subscores, explanations, flags, flagsDetailed, advertised, stats) plus the bulk provenance fields (found, endpoint_id, probes_30d, probed_at, computed_at, recomputed)."}},"required":[]}}}},"402":{"description":"Payment Required"}}}},"/v1/x402-trust-bulk-500":{"post":{"summary":"Bulk trust score for up to 500 endpoints","description":"Score up to 500 x402 endpoints in one call. Every found result carries the FULL trust report — identical to POST /v1/x402-trust (score, grade, scoreRange, recommendation, confidence breakdown, component/subscore breakdown, explanations, flags + flagsDetailed, advertised price, 30-day on-chain stats) — served from cached snapshots. No live re-probe — this is the scale product; for a fresh live probe use /v1/x402-trust. Resources not in our observation set return `found:false`; if NONE of the supplied resources are tracked the request is rejected with 400 `notCharged:true` and you pay nothing. Price: $0.500000 per call.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.500000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","description":"List of full x402 resource URLs. Max 500; fewer allowed; duplicates ignored."}},"required":["resources"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"integer","description":"Unix ms when the response was generated."},"tier":{"type":"integer","description":"Tier size (max endpoints)."},"requested":{"type":"integer","description":"Number of unique resources scored."},"results":{"type":"array","description":"One result per requested resource, in request order. Each found:true row is the full trust report (same fields as POST /v1/x402-trust: score, grade, scoreRange, recommendation, confidenceDetail, breakdown, subscores, explanations, flags, flagsDetailed, advertised, stats) plus the bulk provenance fields (found, endpoint_id, probes_30d, probed_at, computed_at, recomputed)."}},"required":[]}}}},"402":{"description":"Payment Required"}}}}}}