X402 List

MCP server for x402-list: discover x402 payment services and on-chain-verified facilitator settlement volume.

What is x402-list

x402-list is the directory of services that accept x402 (HTTP 402 stablecoin) payments. Its distinctive, defensible data is on-chain-verified settlement volume per facilitator, not self-reported numbers. Listed services are continuously health-monitored (uptime, response time, status).

This package is a thin, read-only wrapper over the public x402-list HTTP JSON API. It holds no keys, touches no database, and makes no writes. It exposes the directory to AI agents through the Model Context Protocol.

Install and quick start

stdio (local MCP clients)

npx -y x402-list-mcp

Claude Desktop / generic MCP client config:

{ "mcpServers": { "x402-list": { "command": "npx", "args": ["-y", "x402-list-mcp"] } } }

Hosted HTTP (Streamable HTTP transport)

MCP_HTTP_PORT=3000 npx -y x402-list-mcp --http

Hosted endpoint: https://mcp.x402-list.com/mcp. Health probe: GET /healthz returns {"status":"ok"}.

Environment variables

Variable	Default	Purpose
X402_LIST_BASE_URL	https://x402-list.com	API base URL. The /api/v1 prefix is appended automatically.
X402_LIST_TIMEOUT_MS	15000	Per-request timeout in milliseconds.
MCP_HTTP_PORT / PORT	3000	HTTP port. Setting MCP_HTTP_PORT selects HTTP transport.
MCP_ALLOWED_ORIGINS	(empty, permissive)	Comma list of allowed CORS origins for HTTP mode.
MCP_ALLOWED_HOSTS	(empty, off)	Comma list that enables DNS-rebinding protection in HTTP mode.

Tools

Tool	What it does
search_x402_services	Search and filter the directory by query, category, network, status; sort by newest/uptime/cheapest/endpoints.
get_service	Full detail for one service by slug: endpoints, per-endpoint USD pricing, uptime windows, networks, settlement asset.
find_best_service	Ranked recommendation for a need. Ranks mostly by reliability, x402 compliance and price (status, verified, uptime, response time, USD price), with a small (~10%) weight on per-service on-chain traction; shared-payout and unmeasured-network services stay neutral.
check_health	Live status, directory-wide or per service (uptime snapshots, consecutive failures).
get_facilitator_volumes	Per-facilitator on-chain-verified settlement volume (24h/7d/30d/all) in USD, tx counts, and an on-chain vs listed flag.

Units note

All monetary values are decimal US dollars and are passed through verbatim. There is no cents conversion anywhere. The per-endpoint pricing[].price field is a raw atomic on-chain token amount (a uint256 string), not dollars; only price_usd is the dollar figure.

Honesty note

Two different on-chain volume signals; do not conflate them. Facilitator volume (get_facilitator_volumes) is the ecosystem headline, aggregated per facilitator. Per-service traction (the traction block on each service, weighed at ~10% inside find_best_service) is settlement measured over a service's own payTo via recognized settlers - a deliberate conservative undercount, not an estimate: unattributed settlements are left out, never scaled up. A service whose payTo is shared across services (operator-level volume, shared_payout: true) or that sits on a network not yet measured carries no per-service figure and stays neutral in the ranking; never read shared or unmeasured volume as one service's revenue. To ask "which facilitators have real on-chain volume", use get_facilitator_volumes and read the verification flag.

Source

The source code is not public yet. This package is a thin read-only wrapper over the public x402-list REST API, documented at https://x402-list.com/api.

License

MIT