{"openapi":"3.1.0","info":{"title":"x402 Trust: trust & reliability data for the x402 ecosystem","version":"2.0.0","description":"Trust and reliability scores for x402 endpoints from continuous 24/7 monitoring: uptime probes, 402-envelope compliance, advertised price history, and real on-chain USDC settlement volume per payTo address. Deterministic and auditable: know before you pay.","x-guidance":"We monitor every publicly listed x402 endpoint 24/7: uptime probes, 402-envelope compliance, price history, and real on-chain USDC settlement volume per payTo address. Buy a trust score before paying an unknown endpoint. Payment: USDC EIP-3009 on Base mainnet (eip155:8453) via the x402 PAYMENT-SIGNATURE header.","contact":{"name":"x402 Trust","url":"https://x402-trust.com"}},"servers":[{"url":"https://x402-trust.com"}],"paths":{"/v1/x402-trust-preview":{"get":{"summary":"Trust preview: full sample reports","description":"Three complete trust reports (best, median, and worst of the current population), exactly as POST /v1/x402-trust returns them. No parameters.","responses":{"200":{"description":"Trust preview (3 full sample reports: best/median/worst)","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Trust preview: full sample reports (POST)","description":"Same as GET /v1/x402-trust-preview: three full sample reports, no parameters.","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, grade A-F) from 30d uptime, 402-envelope compliance, latency, age, on-chain USDC settlement activity, and price stability, with full breakdown and machine-readable flags. Uncataloged endpoints are live-probed on first query and auto-adopted.","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)."},"providerVerified":{"type":"boolean","description":"Present and true when the provider proved domain control + confirmed contact email."},"providerName":{"type":"string","description":"Provider-published organization name (verified providers only)."},"providerContact":{"type":"string","description":"Provider contact email, published after confirmation (verified providers only)."},"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: listing and delisting events, price and payTo changes, and probe results 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":"Semantically similar endpoints that currently out-score a given one, for routing away from a mediocre endpoint toward a more reliable one serving the same function. Same-host siblings and avoid-flagged endpoints are excluded; an empty list means nothing beats the subject.","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","description":"Meaning-based search: describe the capability you need in plain words, get the up to 25 closest endpoints ranked by cosine similarity, then trust score. Discovery only: no verdicts or flags (POST /v1/x402-trust carries those). Per-IP rate limited (429 on excess).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Free-text search query (2-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":"query + count + ranked matches (id, resource, score, grade, similarity, description, endpointPage; score/grade null when unscored)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"query missing or not 2-500 characters"},"429":{"description":"per-IP rate limit exceeded"},"503":{"description":"embedding service or similarity index unavailable, retry shortly"}}}},"/v1/watch-endpoint-30d":{"post":{"summary":"Watch one x402 endpoint for 30 days (change + liveness alerts)","description":"Monitor one listed endpoint for 30 days: alerts on payTo, price, asset or network changes, spec regressions, delisting, and liveness. Push to signed HTTPS webhooks or Slack/Discord URLs (max 5 each), connection-tested before payment. Returns a one-time bearer secret plus poll, edit, and cancel URLs.","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 (bearer-authed)","description":"Two append-only streams: events (endpoint changes) and watch_events (lifecycle feedback). Auth: Authorization: Bearer <secret>. Page with since = next_cursor and watch_since = watch_events_cursor; nothing is lost between polls.","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 (bearer-authed)","description":"Change a watch's webhook or Slack URLs, liveness sensitivity, or subscribed events. New URLs are connection-tested first; if any fails, the existing config stays unchanged. Delivery fields are full-replace per channel.","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 (bearer-authed)","description":"Soft-cancel the watch immediately; the event log stays readable until expiry. 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 stays the same; renewing early adds time from the later of now or the current expiry.","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. Found rows carry the full trust report identical to POST /v1/x402-trust, served from cached snapshots (no live re-probe; for that use /v1/x402-trust). Unknown resources return found:false; if none are tracked the request is rejected with 400 notCharged:true. 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. Found rows carry the full trust report identical to POST /v1/x402-trust, served from cached snapshots (no live re-probe; for that use /v1/x402-trust). Unknown resources return found:false; if none are tracked the request is rejected with 400 notCharged:true. 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. Found rows carry the full trust report identical to POST /v1/x402-trust, served from cached snapshots (no live re-probe; for that use /v1/x402-trust). Unknown resources return found:false; if none are tracked the request is rejected with 400 notCharged:true. 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. Found rows carry the full trust report identical to POST /v1/x402-trust, served from cached snapshots (no live re-probe; for that use /v1/x402-trust). Unknown resources return found:false; if none are tracked the request is rejected with 400 notCharged:true. 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. Found rows carry the full trust report identical to POST /v1/x402-trust, served from cached snapshots (no live re-probe; for that use /v1/x402-trust). Unknown resources return found:false; if none are tracked the request is rejected with 400 notCharged:true. 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"}}}}}}