{ "openapi": "3.1.0", "info": { "title": "x402 List API", "version": "1.0.0", "description": "Public REST API for x402-list.com - the directory of all services using the x402 protocol (HTTP 402 Payment Required). x402 is an open standard by Coinbase for internet-native, agent-first payments. This API provides programmatic access to service listings, uptime monitoring data, pricing information, and network stats. No authentication required for read access. Rate limited to 200 req/min per IP.", "contact": { "name": "x402 List", "url": "https://x402-list.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://x402-list.com/api/v1", "description": "Production" } ], "paths": { "/services": { "get": { "operationId": "listServices", "summary": "List all x402 services", "description": "Returns a paginated list of registered x402 services with computed fields like uptime, pricing, and endpoint count. Supports filtering by network, status, category, and full-text search.", "tags": [ "Services" ], "parameters": [ { "name": "network", "in": "query", "schema": { "type": "string" }, "description": "Filter by single network abbreviation (e.g. BSE, SOL, POL)", "example": "BSE" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "online", "degraded", "offline" ] }, "description": "Filter by service status" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by category (e.g. AI, Data, Compute)", "example": "AI" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "uptime", "cheapest", "endpoints" ], "default": "newest" }, "description": "Sort order" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Full-text search on service name" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "description": "Results per page" } ], "responses": { "200": { "description": "Paginated list of services", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceListItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "example": { "data": [ { "slug": "weather-x402", "name": "Weather x402", "description": "Real-time weather data via x402 micropayments", "base_url": "https://weather-x402.example.com", "category": "Data", "status": "online", "verified": true, "endpoint_count": 3, "min_price_usd": "0.001", "networks": [ "BSE", "SOL" ], "uptime_24h": 99.8, "avg_response_time_ms": 145, "last_checked_at": "2026-04-13T10:30:00Z", "created_at": "2026-03-01T00:00:00Z" } ], "meta": { "total": 15, "page": 1, "per_page": 25, "total_pages": 1 } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/services/{slug}": { "get": { "operationId": "getService", "summary": "Get service detail", "description": "Returns full details for a single service including all active endpoints with their current pricing, uptime windows (24h/7d/30d), average response time, and total check count.", "tags": [ "Services" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service URL slug", "example": "weather-x402" } ], "responses": { "200": { "description": "Service detail with endpoints and pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServiceDetail" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/services/{slug}/uptime": { "get": { "operationId": "getServiceUptime", "summary": "Get service uptime history", "description": "Returns daily uptime snapshots for a service over the specified period. Each data point includes uptime percentage, average response time, and check counts.", "tags": [ "Services" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "weather-x402" }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "default": "30d" }, "description": "Time period" } ], "responses": { "200": { "description": "Array of daily uptime data points", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UptimeDataPoint" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/services/{slug}/checks": { "get": { "operationId": "getServiceChecks", "summary": "Get service check logs", "description": "Returns raw monitoring check logs for a service, ordered by most recent first. Includes status code, response time, and endpoint discovery count.", "tags": [ "Services" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "weather-x402" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Number of results" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset for pagination" } ], "responses": { "200": { "description": "Check logs with total count", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckEntry" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/checks": { "get": { "operationId": "getGlobalChecks", "summary": "Global live feed of all checks", "description": "Returns the most recent monitoring checks across ALL services, ordered by time descending. Useful for building a real-time feed or dashboard of x402 ecosystem health.", "tags": [ "Checks" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Global check feed with total count", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GlobalCheckEntry" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "Global status summary", "description": "Returns aggregate status counts (online/degraded/offline/unknown) and per-service status with uptime and response time. Use this for a quick health overview of the x402 ecosystem.", "tags": [ "Status" ], "responses": { "200": { "description": "Status summary with per-service breakdown", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StatusSummary" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/networks": { "get": { "operationId": "getNetworks", "summary": "List supported blockchain networks", "description": "Returns all blockchain networks that x402 services accept payments on. Each network includes a service count and average uptime. Uses CAIP-2 identifiers.", "tags": [ "Reference" ], "responses": { "200": { "description": "Array of networks with stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Network" } } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/tags": { "get": { "operationId": "getTags", "summary": "List service categories/tags", "description": "Returns all tags (categories) with the count of services in each. Tags include: AI, Data, Compute, Content, Finance.", "tags": [ "Reference" ], "responses": { "200": { "description": "Array of tags with service counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/stats": { "get": { "operationId": "getStats", "summary": "Aggregate ecosystem statistics", "description": "Returns aggregate statistics about the x402 ecosystem: total services, endpoints, networks, uptime averages, response time averages, checks per hour, and pricing aggregates (avg/min/max/median price in USD).", "tags": [ "Stats" ], "responses": { "200": { "description": "Aggregate stats with pricing breakdown", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AggregateStats" } } }, "example": { "data": { "total_services": 15, "total_endpoints": 55, "total_networks": 3, "avg_uptime_24h": 94.2, "avg_uptime_7d": 93.8, "avg_response_time_ms": 182, "checks_per_hour": 60, "pricing": { "avg_price_usd": 0.042, "min_price_usd": 0.001, "max_price_usd": 0.1, "median_price_usd": 0.025 }, "networks": [ { "abbreviation": "BSE", "service_count": 12, "avg_uptime": 95.1 } ] } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/categories": { "get": { "operationId": "getCategories", "summary": "List service categories", "description": "Returns the distinct list of categories currently used by listed services. Useful for populating filter dropdowns or submission forms.", "tags": [ "Reference" ], "responses": { "200": { "description": "List of category strings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } } }, "example": { "data": [ "AI", "Compute", "Content", "Data", "Finance" ] } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/submit": { "post": { "operationId": "submitService", "summary": "Submit a new service for review", "description": "Submit a new x402-compatible service to be reviewed and listed in the directory. The service will be automatically probed for valid HTTP 402 responses on the provided endpoints, then manually reviewed before appearing in the directory. All fields are required except notes.", "tags": [ "Submissions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "email", "service_name", "description", "website_url", "category", "endpoints" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Base URL of the x402 service" }, "email": { "type": "string", "format": "email", "description": "Submitter contact email" }, "service_name": { "type": "string", "description": "Human-readable name of the service" }, "description": { "type": "string", "description": "Brief description of what the service does" }, "website_url": { "type": "string", "format": "uri", "description": "Public website URL" }, "category": { "type": "string", "description": "Service category (use /categories to get valid values)" }, "endpoints": { "type": "array", "items": { "type": "string" }, "description": "List of endpoint paths to probe (e.g. [\"/v1/generate\", \"/v1/translate\"])" }, "notes": { "type": "string", "description": "Optional additional context" } } }, "example": { "url": "https://api.example.com", "email": "dev@example.com", "service_name": "Example x402 API", "description": "AI-powered text generation via x402 payments", "website_url": "https://example.com", "category": "AI", "endpoints": [ "/v1/generate", "/v1/classify" ], "notes": "Supports both Base and Solana networks" } } } }, "responses": { "201": { "description": "Submission created, pending review", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "submission_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "probe_result": { "type": [ "object", "null" ], "properties": { "endpoints_found": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "schemas": { "ServiceListItem": { "type": "object", "description": "A service in the directory listing with computed summary fields", "properties": { "slug": { "type": "string", "description": "URL-friendly identifier", "example": "weather-x402" }, "name": { "type": "string", "example": "Weather x402" }, "description": { "type": "string" }, "base_url": { "type": "string", "format": "uri" }, "website_url": { "type": [ "string", "null" ], "format": "uri" }, "category": { "type": "string", "example": "Data" }, "status": { "type": "string", "enum": [ "online", "degraded", "offline", "unknown" ] }, "verified": { "type": "boolean" }, "endpoint_count": { "type": "integer", "description": "Number of active endpoints" }, "min_price_usd": { "type": [ "string", "null" ], "description": "Lowest price in USD across all endpoints" }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Network abbreviations supported by this service (e.g. [\"BSE\", \"SOL\"])" }, "uptime_24h": { "type": [ "number", "null" ], "description": "Uptime percentage over last 24 hours" }, "avg_response_time_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "ServiceDetail": { "type": "object", "description": "Full service detail including endpoints with pricing", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "base_url": { "type": "string", "format": "uri" }, "website_url": { "type": [ "string", "null" ], "format": "uri" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "degraded", "offline", "unknown" ] }, "verified": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "check_interval_minutes": { "type": "integer" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "uptime": { "type": "object", "properties": { "24h": { "type": "number" }, "7d": { "type": "number" }, "30d": { "type": "number" }, "90d": { "type": "number" } } }, "avg_response_time_ms": { "type": [ "integer", "null" ] }, "total_checks": { "type": "integer" }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Network abbreviations aggregated across all active endpoints" }, "asset": { "type": "string", "description": "Primary payment asset (e.g. USDC)" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } }, "Endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "example": "GET" }, "path": { "type": "string", "example": "/v1/forecast" }, "description": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "min_price_usd": { "type": [ "number", "null" ] }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Network abbreviations for this endpoint" }, "pricing": { "type": "array", "items": { "$ref": "#/components/schemas/PricingEntry" } } } }, "PricingEntry": { "type": "object", "description": "Current pricing for an endpoint on a specific network", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "description": "CAIP-2 network ID", "example": "eip155:8453" }, "asset_address": { "type": "string" }, "asset_name": { "type": "string", "example": "USDC" }, "price": { "type": "string", "description": "Price in native asset units" }, "price_usd": { "type": "string", "description": "Price in USD" }, "pay_to": { "type": "string", "description": "Payment recipient address" }, "max_timeout_seconds": { "type": [ "integer", "null" ] } } }, "UptimeDataPoint": { "type": "object", "description": "Daily uptime snapshot for a service", "properties": { "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "uptime_percentage": { "type": "number", "example": 99.5 }, "avg_response_time_ms": { "type": "number" }, "total_checks": { "type": "integer" }, "successful_checks": { "type": "integer" } } }, "CheckEntry": { "type": "object", "description": "A single monitoring check result", "properties": { "id": { "type": "string", "format": "uuid" }, "checked_at": { "type": "string", "format": "date-time" }, "response_time_ms": { "type": [ "integer", "null" ] }, "status_code": { "type": [ "integer", "null" ] }, "is_up": { "type": "boolean" }, "error_message": { "type": [ "string", "null" ] }, "endpoints_found": { "type": "integer" } } }, "GlobalCheckEntry": { "type": "object", "description": "A check entry with service info, for the global live feed", "properties": { "id": { "type": "string", "format": "uuid" }, "checked_at": { "type": "string", "format": "date-time" }, "is_up": { "type": "boolean" }, "response_time_ms": { "type": [ "integer", "null" ] }, "status_code": { "type": [ "integer", "null" ] }, "endpoints_found": { "type": "integer" }, "service_name": { "type": "string" }, "service_slug": { "type": "string" }, "service_status": { "type": "string", "enum": [ "online", "degraded", "offline", "unknown" ] } } }, "StatusSummary": { "type": "object", "properties": { "total": { "type": "integer" }, "online": { "type": "integer" }, "degraded": { "type": "integer" }, "offline": { "type": "integer" }, "unknown": { "type": "integer" }, "services": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "degraded", "offline", "unknown" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "type": "integer" }, "uptime_24h": { "type": [ "number", "null" ] }, "avg_response_time_ms": { "type": [ "number", "null" ] } } } } } }, "Network": { "type": "object", "description": "A blockchain network that x402 services accept payments on", "properties": { "id": { "type": "string", "format": "uuid" }, "caip2_id": { "type": "string", "description": "CAIP-2 chain identifier", "example": "eip155:8453" }, "name": { "type": "string", "example": "Base" }, "abbreviation": { "type": "string", "example": "BSE" }, "chain_type": { "type": "string", "example": "evm" }, "is_mainnet": { "type": "boolean" }, "explorer_url": { "type": "string", "format": "uri" }, "service_count": { "type": "integer", "description": "Number of services accepting payments on this network" }, "avg_uptime": { "type": "number", "description": "Average uptime % of services on this network" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "AI" }, "slug": { "type": "string", "example": "ai" }, "service_count": { "type": "integer" } } }, "AggregateStats": { "type": "object", "description": "Aggregate statistics about the x402 ecosystem", "properties": { "total_services": { "type": "integer" }, "total_endpoints": { "type": "integer" }, "total_networks": { "type": "integer" }, "avg_uptime_24h": { "type": "number" }, "avg_uptime_7d": { "type": "number" }, "avg_response_time_ms": { "type": "integer" }, "checks_per_hour": { "type": "integer" }, "pricing": { "type": "object", "properties": { "avg_price_usd": { "type": "number" }, "min_price_usd": { "type": "number" }, "max_price_usd": { "type": "number" }, "median_price_usd": { "type": "number" } } }, "networks": { "type": "array", "items": { "type": "object", "properties": { "abbreviation": { "type": "string" }, "service_count": { "type": "integer" }, "avg_uptime": { "type": "number" } } } } } }, "PaginationMeta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of results" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Results per page" }, "total_pages": { "type": "integer", "description": "Total number of pages" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } } }, "responses": { "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": 404, "message": "Service not found" } } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": 500, "message": "Internal server error" } } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": 429, "message": "Too many requests. Please slow down." } } } } } } }, "tags": [ { "name": "Services", "description": "Browse and query x402 services, their endpoints, uptime, and pricing" }, { "name": "Checks", "description": "Access monitoring check logs - the raw heartbeat of the x402 ecosystem" }, { "name": "Status", "description": "Get a quick health overview of all monitored services" }, { "name": "Stats", "description": "Aggregate statistics about the x402 ecosystem" }, { "name": "Reference", "description": "Reference data: supported networks, categories, and service tags" }, { "name": "Submissions", "description": "Submit new x402 services for review and listing" } ] }