x402 List

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

All endpoints return JSON. No authentication required for read access. Rate limit: 100 req/min. You can also browse the service directory or submit a new service via the web interface.

GET /api/v1/services

Returns a paginated list of all registered x402 services.

Query Parameters

Example Response

{
  "data": [
    {
      "slug": "weather-x402",
      "name": "weather-x402",
      "description": "Weather forecast API with 7-day outlook",
      "url": "https://weather-x402.example.com",
      "network": "base",
      "status": "online",
      "endpoints": 5,
      "price_per_request": "$0.01",
      "uptime_24h": 99.8,
      "uptime_7d": 99.9,
      "avg_response_ms": 142,
      "last_checked_at": "2026-04-13T14:23:01Z",
      "tags": ["weather", "forecast"]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 47,
    "total_pages": 3
  }
}

GET /api/v1/services/:slug

Returns full details for a single service, including all endpoint paths and pricing.

Example Response

{
  "data": {
    "slug": "weather-x402",
    "name": "weather-x402",
    "description": "Weather forecast API with 7-day outlook",
    "url": "https://weather-x402.example.com",
    "network": "base",
    "status": "online",
    "endpoints": [
      { "path": "/forecast", "price": "$0.01", "method": "GET" },
      { "path": "/current", "price": "$0.005", "method": "GET" }
    ],
    "uptime_24h": 99.8,
    "uptime_7d": 99.9,
    "uptime_30d": 99.7,
    "avg_response_ms": 142,
    "last_checked_at": "2026-04-13T14:23:01Z",
    "tags": ["weather", "forecast"],
    "submitted_at": "2026-01-15T09:00:00Z"
  }
}

GET /api/v1/services/:slug/uptime

Returns uptime percentage and time-series data for the specified period.

Query Parameters

Example Response

{
  "data": {
    "slug": "weather-x402",
    "period": "24h",
    "uptime_pct": 99.8,
    "total_checks": 1440,
    "successful_checks": 1437,
    "timeseries": [
      { "t": "2026-04-13T00:00:00Z", "up": true, "ms": 138 },
      { "t": "2026-04-13T01:00:00Z", "up": true, "ms": 145 }
    ]
  }
}

GET /api/v1/services/:slug/checks

Returns individual health-check results for a service, newest first.

Query Parameters

Example Response

{
  "data": [
    {
      "id": "chk_a1b2c3",
      "checked_at": "2026-04-13T14:23:01Z",
      "status": "online",
      "response_ms": 142,
      "http_status": 402
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "total": 1440
  }
}

GET /api/v1/checks

Live feed of health checks across all services, newest first. Useful for building real-time dashboards.

Example Response

{
  "data": [
    {
      "id": "chk_x9y8z7",
      "service_slug": "price-oracle",
      "checked_at": "2026-04-13T14:22:58Z",
      "status": "online",
      "response_ms": 34,
      "http_status": 402
    },
    {
      "id": "chk_d4e5f6",
      "service_slug": "image-classify",
      "checked_at": "2026-04-13T14:22:40Z",
      "status": "offline",
      "response_ms": null,
      "http_status": null
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "total": 84200
  }
}

GET /api/v1/status

Aggregate platform health. Returns counts of online, degraded, and offline services.

Example Response

{
  "data": {
    "status": "operational",
    "services_online": 44,
    "services_degraded": 2,
    "services_offline": 1,
    "services_total": 47,
    "avg_response_ms": 168,
    "checked_at": "2026-04-13T14:23:01Z"
  }
}

GET /api/v1/networks

Lists all blockchain networks tracked by x402 List, with service counts.

Example Response

{
  "data": [
    { "slug": "base", "name": "Base", "services": 7, "avg_uptime": 98.4 },
    { "slug": "solana", "name": "Solana", "services": 4, "avg_uptime": 97.9 },
    { "slug": "polygon", "name": "Polygon", "services": 2, "avg_uptime": 99.4 }
  ]
}

GET /api/v1/tags

Lists all tags with the number of services using each tag.

Example Response

{
  "data": [
    { "slug": "ai", "label": "AI", "count": 12 },
    { "slug": "weather", "label": "Weather", "count": 3 },
    { "slug": "oracle", "label": "Oracle", "count": 5 }
  ]
}

GET /api/v1/stats

Platform-wide aggregate statistics.

Example Response

{
  "data": {
    "total_services": 47,
    "total_endpoints": 312,
    "total_networks": 3,
    "avg_price_per_request": 0.052,
    "avg_response_ms": 168,
    "avg_uptime_24h": 98.7,
    "avg_uptime_7d": 99.1,
    "checks_per_hour": 1440
  }
}

POST /api/v1/submit

Submit a new x402-compatible service for review and inclusion in the directory.

Request Body (JSON)

Example Request

curl -X POST https://x402-list.com/api/v1/submit \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-service.example.com",
    "email": "operator@example.com",
    "notes": "AI image generation service on Base",
    "endpoint_paths": ["/generate", "/upscale"]
  }'

Example Response

{
  "data": {
    "submission_id": "sub_m3n4o5",
    "status": "pending_review",
    "created_at": "2026-04-13T15:00:00Z"
  }
}

GET /api/v1/openapi.json

Returns the full OpenAPI 3.1 specification for this API. Use it to auto-generate client libraries or import into tools like Postman.

Response Format

All successful responses follow a consistent envelope structure:

{
  "data": { ... },   // object or array — the requested resource(s)
  "meta": { ... }    // pagination info, totals (present on list endpoints)
}

Error responses use the same envelope with an error key:

{
  "error": {
    "code": "not_found",
    "message": "Service with slug 'foo' does not exist."
  }
}

HTTP Status Codes

Rate Limiting

All endpoints are rate-limited to 100 requests per minute per IP address. Rate limit status is returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1744545840

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.