Fuchss · Semantic Search

Semantic search across the entire monitored x402 catalog. Given a free-text query (e.g. "weather forecast", "image generation", "EVM gas price oracle"), returns the closest endpoints by advertised purpose. Ranking is deterministic: cosine similarity bucketed to whole percentage points first (80.3% and 80.5% are the same bucket), then trust score, then described-before-undescribed, then endpoint id. Matches below a 0.5 cosine-similarity floor are dropped entirely, so a query can return fewer than the requested limit (or none). Endpoints that advertise no description are still matched: they are embedded from their service name and URL path tokens instead of a written description (host name as a last resort). The exact effect of a missing description: no fixed point deduction and no direct similarity malus; the only deterministic penalty is the described-before-undescribed tiebreak (at equal similarity bucket AND equal trust score, a described endpoint ranks first). Beyond that it is purely indirect: the shorter fallback text typically yields lower cosine similarity than a prose description, so such endpoints tend to land in lower similarity buckets, by a query-dependent amount. Each match carries its resource URL, trust score, grade, cosine similarity (0-1, raw value; ranking buckets it), advertised description when present, and a free endpoint-page URL. Matches also carry the advertised price as machine-readable fields: amountUsd (null when not advertised) and priceCeiling (true when the endpoint uses the x402 'upto' scheme, i.e. amountUsd is an authorization ceiling and the real charge is typically lower). This is a DISCOVERY product: it deliberately carries no verdict, recommendation or flag detail (the per-endpoint trust report sold at /v1/x402-trust carries those). The query is embedded with the same model as the catalog, so phrasing the capability you need works better than guessing keywords.

import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const fetchWithPay = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPay("https://x402.fuchss.app/v1/semantic-search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "limit": 25,
    "query": "weather forecast"
  }),
});
const data = await res.json();

curl -X POST \
  "https://x402.fuchss.app/v1/semantic-search" \
  -H "Content-Type: application/json" \
  -d '{"limit":25,"query":"weather forecast"}' \
  -H "X-PAYMENT: <signed x402 payment>"

{
  "count": 2,
  "generatedAt": 1782826208450,
  "matches": [
    {
      "amountUsd": 0.002,
      "description": "Hyperlocal weather forecasts, priced per call.",
      "endpointPage": "https://x402.fuchss.app/endpoint/12345",
      "grade": "A",
      "id": 12345,
      "priceCeiling": false,
      "resource": "https://api.weather.example/v1/forecast",
      "score": 88.1,
      "similarity": 0.912
    },
    {
      "amountUsd": null,
      "description": null,
      "endpointPage": "https://x402.fuchss.app/endpoint/12399",
      "grade": null,
      "id": 12399,
      "priceCeiling": false,
      "resource": "https://wx.example.net/api/now",
      "score": null,
      "similarity": 0.874
    }
  ],
  "note": "Ranked by cosine similarity, with trust score as a tiebreaker. score/grade are null when the endpoint is not yet scored. No verdict or flag detail here: POST /v1/x402-trust carries those.",
  "query": "weather forecast"
}