# x402 List - Full Context for LLMs

> x402 List is the **agent-first** canonical open directory of x402 protocol services. It indexes APIs that accept payments via the HTTP 402 Payment Required standard and exposes every service, uptime metric, and price as machine-readable JSON. The site is designed primarily for consumption by AI agents and automated systems, while remaining fully browsable by humans.

## What is x402?

x402 is an open protocol for machine-native API payments. When a client sends a request to an x402-protected endpoint without payment, the server responds with HTTP 402 and a JSON body specifying accepted payment methods (blockchain networks, asset addresses, prices). The client can then attach payment proof to a subsequent request to gain access. No API keys, no signup, no subscriptions. Any agent with a funded wallet can discover, evaluate, and pay for any x402 service without human intervention.

## Who this directory is for

Primary audience: AI agents, agent frameworks, aggregators, and developer tools that need to discover and integrate x402 services programmatically. Secondary audience: human developers browsing the directory to find reliable x402 APIs. Every piece of data rendered in HTML has an equivalent JSON representation at /api/v1/*.

## What this site contains

- A searchable directory of x402-compatible API services
- Real-time uptime monitoring and status for each service
- Pricing data per endpoint (USD and crypto)
- Network support information (Base, Solana, Polygon, etc.)
- Historical uptime charts and response time tracking
- ASCII sparkline summaries for quick status overview

## Site structure

### Pages

- `/` - Homepage dashboard with service listings, live feed, and stats
- `/services` - Full directory with filters (network, category, status, sort) and full-text search across name, description, and category
- `/services/{slug}` - Service detail: endpoints, pricing, uptime charts, check log
- `/status` - System-wide monitoring dashboard with uptime matrix
- `/submit` - Submit a new x402 service for review (moderated)
- `/about` - About the x402 protocol and this project
- `/api` - REST API documentation with quick-start curl examples
- `/learn` - Articles and guides about x402
- `/learn/what-is-x402` - What is the x402 protocol?
- `/learn/x402-vs-api-keys` - x402 vs traditional API payments
- `/learn/ai-agents-x402` - How AI agents use x402 for payments

### REST API

Base URL: `https://x402-list.com/api/v1/`

All endpoints return JSON. No authentication required for reads. Rate limit: 200 req/min per IP (soft-throttled above 100 req/min via `X-RateLimit-Throttled: true` header - requests still succeed). Responses include `ETag` and `Last-Modified` for conditional requests.

- `GET /api/v1/services` - List services with filters (network, status, category), sorting (newest, uptime, cheapest, endpoints), pagination, and full-text search (`?q=`)
- `GET /api/v1/services/{slug}` - Service detail with endpoints and pricing
- `GET /api/v1/services/{slug}/uptime` - Historical uptime data
- `GET /api/v1/services/{slug}/checks` - Recent check log
- `GET /api/v1/checks` - Global live feed of all checks
- `GET /api/v1/status` - Global status summary
- `GET /api/v1/networks` - Supported networks with service counts
- `GET /api/v1/tags` - Service categories with counts
- `GET /api/v1/stats` - Aggregate statistics
- `GET /api/v1/categories` - Category list for dropdowns
- `GET /api/v1/openapi.json` - OpenAPI 3.1 specification
- `POST /api/v1/submit` - Submit a new service (requires all fields)

All timestamp fields in API responses are normalized to ISO 8601 UTC (e.g. `2026-04-15T12:50:01.459Z`). Response envelope is `{ "data": ..., "meta": ... }` for success and `{ "error": { "code", "message" } }` for errors.

### Machine-readable resources

- `/openapi.json` - OpenAPI 3.1 specification (301 redirect to `/api/v1/openapi.json`, standard convention)
- `/api/v1/openapi.json` - Canonical OpenAPI 3.1 specification
- `/sitemap.xml` - XML sitemap (includes dynamic service pages)
- `/feed.xml` - RSS 2.0 feed for new learn articles and services
- `/robots.txt` - Crawler directives (AI crawlers explicitly allowed)
- `/llms.txt` - Short summary for LLMs
- `/llms-full.txt` - This file (extended context)

## Data model

Each service has:
- Name, slug, base URL, description, category
- Status (online/degraded/offline/unknown) - determined by monitoring with hysteresis (3 consecutive failures → offline, 2 consecutive successes → online)
- Verified flag (manually moderated before listing)
- Multiple endpoints, each with HTTP method, path, description, MIME type, active flag
- Pricing per endpoint: price in crypto + USD equivalent, network (CAIP-2 id), asset address
- Daily uptime snapshots aggregated from periodic health checks (cron every minute, per-service interval 15 min default)
- Last-checked timestamp and consecutive-failures counter

## How to use the API as an AI agent

1. **Discover services**: `GET /api/v1/services?category=AI&status=online&sort=uptime` - filter by category, network, or status; sort by uptime, price, or response time; search with `?q=`
2. **Get details**: `GET /api/v1/services/{slug}` for the full list of endpoints, prices, and supported networks
3. **Check uptime**: `GET /api/v1/services/{slug}/uptime?period=7d` for historical reliability
4. **Construct the call**: the service's `base_url` + endpoint `path` gives you the actual x402 API URL
5. **Make the x402 request**: send a request to that URL. If you get HTTP 402, parse the `accepts[]` array from the response body to get accepted networks, asset addresses, prices, and the `payTo` address
6. **Pay and retry**: construct a blockchain transaction per the 402 requirements, then retry the original request with the payment proof attached
7. **Enforce budgets**: the price is always declared before any money moves. Apply per-request caps, per-task budgets, and per-session maximums before proceeding

## Submission flow

Anyone can submit a new x402 service at `/submit` (form) or `POST /api/v1/submit` (JSON). Submissions are automatically probed to confirm the endpoint returns a valid 402 response with a well-formed `accepts[]` payload. All submissions require manual admin approval before being listed (moderated directory). Once approved, monitoring begins immediately.

## Monitoring model

- Checks run every minute via a dedicated worker (node-cron, UTC timezone)
- Each service has a configurable interval (default 15 min between checks)
- Max 10 concurrent checks via semaphore
- Status hysteresis: 3 consecutive failures → offline, 2 consecutive successes → online, partial endpoint availability → degraded
- Pricing is re-synced on each check: if probed prices differ from DB, the old ones are marked non-current and the new ones inserted
- Daily snapshots aggregate raw checks into `check_snapshots` for sparkline and uptime-window queries
- Raw checks older than 30 days are cleaned up daily

## Deployment and infrastructure

The site is a single Astro SSR app running on Node.js, backed by PostgreSQL 17. A separate worker container handles the cron-driven monitoring. Both containers are deployed via Coolify behind Traefik with HTTP/2 and HTTP/3 enabled, automatic TLS, and security headers (HSTS 2 years preload, CSP with script-src self + analytics subdomain, X-Frame-Options DENY, X-Content-Type-Options nosniff, Referrer-Policy strict-origin-when-cross-origin). CORS is open for read endpoints (`Access-Control-Allow-Origin: *`) with preflight cached for 24 hours.