Recommend the best x402 service(s) for a need
Ranks the directory and returns the best x402 service(s) for a stated need, in one request (no paging). The ranking is the same two-stage relevance-then-quality scoring the MCP x402_find_best_service tool uses, run server-side. It is scored mostly on per-service reliability (live status, verification, uptime, response time), x402 compliance, and price (USD), filtered by category and network, with a SMALL (about 10%) weight on on-chain traction (settlement volume, transaction count, and unique buyers measured per service over its known payTo via recognized settlers, a conservative undercount). A deterministic danger flag removes a service from this surface entirely (its slug is listed in excluded_danger); a residual warning is penalized but kept. When a free-text q is given, each candidate is also scored on how well the query matches its AI-derived capability tags and summary plus its name/description/category (falling back to a plain substring match). The x402 compliance term is the share of deterministic conformance checks the service passes, capped at 0.6 (the floor of the C band) when at least one of its EVM routes is missing the EIP-712 domain parameters a standard x402 client needs in order to sign a payment. That cap is a statement about the payment envelope, not about the merit of the service, and it is what moved the scoring to generation 2. The generation served today is 3, which also gates the on-chain traction term on an absolute 30-day volume floor, discounts a payout concentrated on one buyer, and scores a service that publishes no payTo as zero instead of renormalizing around it. Scores produced under an earlier generation are not comparable with these; meta.ranking_version on every response says which one produced it. This endpoint is free and metered like every other GET on /api/v1/* (beyond the free daily quota it answers 402; see the metering note). Prices are decimal US dollars.
Request
- Base URL: https://x402-list.com/api/v1
- URL: https://x402-list.com/api/v1/best
- Auth: none declared
Query parameters
Free-text need description, matched against each service name/description/category plus its AI-derived capability tags and summary.
Desired service category from the closed category set (case-insensitive). A value outside the set returns 400; omit for all.
Required network name or abbreviation, e.g. "Base" or "BSE". A value outside the known network set returns 400.
Cap on min_price_usd in US dollars; a service priced cheaper or equal passes (a service with no known price is excluded).
If true, only FORTE-tier verified services are eligible (treno D3: a paid delivery-probe settled and delivered, drift-revocable; the payment-ready base tier is NOT included). A hard filter on the eligible pool, not a scoring input, so it does not change ranking_version. A value other than true/false returns 400.
Tie-breaking emphasis for the ranking weights. A value outside the enum returns 400.
How many ranked recommendations to return (clamped to 1-20).
If true, also return top facilitators by 7d settlement volume as separate ecosystem context (NOT per-service). A value other than true/false returns 400.
Response
Ranked recommendations plus the ranking basis and any danger-excluded slugs. meta.ranking_version pins the scoring generation.
Example response
{
"provenance": {
"attribution": "Data: x402-list.com (CC BY 4.0)",
"cite_as": "https://x402-list.com/services/acme-generate",
"source": "https://x402-list.com"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.