{ "openapi": "3.0.0", "info": { "title": "x402 Discovery API", "description": "Discover x402-compatible services that accept USDC payments.\n\nThis API returns a catalog of available services with their payment requirements,\nschemas, and metadata. Services can be filtered by various criteria including\nprotocol type, blockchain network, payment token, and price.", "version": "2.0.0", "contact": { "name": "Circle Developer Support", "url": "https://developers.circle.com/gateway/nanopayments/concepts/x402" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://api.circle.com", "description": "Circle x402 Discovery API" } ], "tags": [ { "name": "Discovery v1", "description": "x402 Discovery API v1 endpoints" }, { "name": "Discovery v2", "description": "x402 Discovery API v2 endpoints" } ], "components": { "schemas": { "ServiceMetadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] }, "PaymentRequirementsV1": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "description": "Payment scheme", "example": "exact" }, "resource": { "type": "string", "description": "Resource URL" }, "description": { "type": "string", "description": "Resource description" }, "mimeType": { "type": "string", "description": "Response MIME type" }, "maxTimeoutSeconds": { "type": "number", "description": "Maximum timeout in seconds" }, "outputSchema": { "type": "object", "additionalProperties": { "nullable": true } }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional metadata" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme", "resource", "description", "mimeType", "maxTimeoutSeconds", "outputSchema", "extra" ] }, "PaymentRequirementsV2": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "enum": [ "exact" ], "description": "Payment scheme" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme" ] }, "PaginationMetadata": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of results returned", "example": 50 }, "offset": { "type": "integer", "minimum": 0, "description": "Number of results skipped", "example": 0 }, "total": { "type": "integer", "minimum": 0, "description": "Total count of resources matching the query", "example": 42 } }, "required": [ "limit", "offset", "total" ] }, "DiscoveryResourceV1": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri", "description": "Resource URL", "example": "https://api.example.com/v1/service" }, "type": { "type": "string", "enum": [ "http", "mcp" ], "description": "Protocol type", "example": "http" }, "x402Version": { "type": "number", "description": "x402 protocol version", "example": 1 }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "description": "Payment scheme", "example": "exact" }, "resource": { "type": "string", "description": "Resource URL" }, "description": { "type": "string", "description": "Resource description" }, "mimeType": { "type": "string", "description": "Response MIME type" }, "maxTimeoutSeconds": { "type": "number", "description": "Maximum timeout in seconds" }, "outputSchema": { "type": "object", "additionalProperties": { "nullable": true } }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional metadata" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme", "resource", "description", "mimeType", "maxTimeoutSeconds", "outputSchema", "extra" ] }, "description": "Accepted payment configurations" }, "metadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] } }, "required": [ "resource", "type", "x402Version" ] }, "DiscoveryResourceV2": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri", "description": "Resource URL", "example": "https://api.example.com/v1/service" }, "type": { "type": "string", "enum": [ "http", "mcp" ], "description": "Protocol type", "example": "http" }, "x402Version": { "type": "number", "description": "x402 protocol version", "example": 2 }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "enum": [ "exact" ], "description": "Payment scheme" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme" ] }, "description": "Accepted payment configurations" }, "metadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] } }, "required": [ "resource", "type", "x402Version" ] }, "DiscoveryResourcesResponseV1": { "type": "object", "properties": { "x402Version": { "type": "number", "enum": [ 1 ], "description": "x402 protocol version" }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri", "description": "Resource URL", "example": "https://api.example.com/v1/service" }, "type": { "type": "string", "enum": [ "http", "mcp" ], "description": "Protocol type", "example": "http" }, "x402Version": { "type": "number", "description": "x402 protocol version", "example": 1 }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "description": "Payment scheme", "example": "exact" }, "resource": { "type": "string", "description": "Resource URL" }, "description": { "type": "string", "description": "Resource description" }, "mimeType": { "type": "string", "description": "Response MIME type" }, "maxTimeoutSeconds": { "type": "number", "description": "Maximum timeout in seconds" }, "outputSchema": { "type": "object", "additionalProperties": { "nullable": true } }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional metadata" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme", "resource", "description", "mimeType", "maxTimeoutSeconds", "outputSchema", "extra" ] }, "description": "Accepted payment configurations" }, "metadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] } }, "required": [ "resource", "type", "x402Version" ] }, "description": "List of discovered resources" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of results returned", "example": 50 }, "offset": { "type": "integer", "minimum": 0, "description": "Number of results skipped", "example": 0 }, "total": { "type": "integer", "minimum": 0, "description": "Total count of resources matching the query", "example": 42 } }, "required": [ "limit", "offset", "total" ] } }, "required": [ "x402Version", "items", "pagination" ] }, "DiscoveryResourcesResponseV2": { "type": "object", "properties": { "x402Version": { "type": "number", "enum": [ 2 ], "description": "x402 protocol version" }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri", "description": "Resource URL", "example": "https://api.example.com/v1/service" }, "type": { "type": "string", "enum": [ "http", "mcp" ], "description": "Protocol type", "example": "http" }, "x402Version": { "type": "number", "description": "x402 protocol version", "example": 2 }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "enum": [ "exact" ], "description": "Payment scheme" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme" ] }, "description": "Accepted payment configurations" }, "metadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] } }, "required": [ "resource", "type", "x402Version" ] }, "description": "List of discovered resources" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of results returned", "example": 50 }, "offset": { "type": "integer", "minimum": 0, "description": "Number of results skipped", "example": 0 }, "total": { "type": "integer", "minimum": 0, "description": "Total count of resources matching the query", "example": 42 } }, "required": [ "limit", "offset", "total" ] } }, "required": [ "x402Version", "items", "pagination" ] }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "description": "Circle error code (NOT HTTP status code)", "example": 2 }, "message": { "type": "string", "description": "Error message", "example": "Invalid query parameter: maxUsdPrice must be a positive number" }, "errors": { "type": "array", "items": { "nullable": true }, "description": "Additional error details" } }, "required": [ "code", "message" ] } }, "parameters": {} }, "paths": { "/v1/x402/discovery/resources": { "get": { "summary": "List discovery resources (v1)", "description": "Returns x402-compatible discovery resources with payment information and schemas.\nV1 format includes output schema within the accepts array.", "tags": [ "Discovery v1" ], "parameters": [ { "schema": { "type": "string", "description": "Fuzzy search query (searches resource URL, provider, description, categories)" }, "required": false, "description": "Fuzzy search query (searches resource URL, provider, description, categories)", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Filter by service category", "example": "PREDICTION_MARKETS" }, "required": false, "description": "Filter by service category", "name": "category", "in": "query" }, { "schema": { "type": "string", "enum": [ "http", "mcp" ], "description": "Filter by protocol type", "example": "http" }, "required": false, "description": "Filter by protocol type", "name": "type", "in": "query" }, { "schema": { "type": "string", "description": "Filter by blockchain network. Accepts CAIP-2 format (e.g., eip155:8453) or legacy SDK names (e.g., base, base-sepolia)", "example": "eip155:8453" }, "required": false, "description": "Filter by blockchain network. Accepts CAIP-2 format (e.g., eip155:8453) or legacy SDK names (e.g., base, base-sepolia)", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "Filter by payment token contract address" }, "required": false, "description": "Filter by payment token contract address", "name": "asset", "in": "query" }, { "schema": { "type": "string", "enum": [ "exact" ], "description": "Filter by payment scheme" }, "required": false, "description": "Filter by payment scheme", "name": "scheme", "in": "query" }, { "schema": { "type": "string", "description": "Filter by merchant wallet address" }, "required": false, "description": "Filter by merchant wallet address", "name": "payTo", "in": "query" }, { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Maximum price per request in USD", "example": 0.01 }, "required": false, "description": "Maximum price per request in USD", "name": "maxUsdPrice", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter by Sign-in with X support. Set to true for only SIWX endpoints, false for only non-SIWX endpoints, or omit for all endpoints", "example": false }, "required": false, "description": "Filter by Sign-in with X support. Set to true for only SIWX endpoints, false for only non-SIWX endpoints, or omit for all endpoints", "name": "siwx", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter to only endpoints that support vanilla x402 payments (non-Circle Gateway)", "example": true }, "required": false, "description": "Filter to only endpoints that support vanilla x402 payments (non-Circle Gateway)", "name": "supportsVanillax402", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter to only endpoints that support Circle Gateway payments", "example": true }, "required": false, "description": "Filter to only endpoints that support Circle Gateway payments", "name": "supportsCircleGateway", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated list of fields to include in response", "example": "resource,type,accepts" }, "required": false, "description": "Comma-separated list of fields to include in response", "name": "fields", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of results to return", "example": 50 }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of results to skip for pagination", "example": 0 }, "required": false, "description": "Number of results to skip for pagination", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "number", "enum": [ 1 ], "description": "x402 protocol version" }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri", "description": "Resource URL", "example": "https://api.example.com/v1/service" }, "type": { "type": "string", "enum": [ "http", "mcp" ], "description": "Protocol type", "example": "http" }, "x402Version": { "type": "number", "description": "x402 protocol version", "example": 1 }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "description": "Payment scheme", "example": "exact" }, "resource": { "type": "string", "description": "Resource URL" }, "description": { "type": "string", "description": "Resource description" }, "mimeType": { "type": "string", "description": "Response MIME type" }, "maxTimeoutSeconds": { "type": "number", "description": "Maximum timeout in seconds" }, "outputSchema": { "type": "object", "additionalProperties": { "nullable": true } }, "extra": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional metadata" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme", "resource", "description", "mimeType", "maxTimeoutSeconds", "outputSchema", "extra" ] }, "description": "Accepted payment configurations" }, "metadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] } }, "required": [ "resource", "type", "x402Version" ] }, "description": "List of discovered resources" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of results returned", "example": 50 }, "offset": { "type": "integer", "minimum": 0, "description": "Number of results skipped", "example": 0 }, "total": { "type": "integer", "minimum": 0, "description": "Total count of resources matching the query", "example": 42 } }, "required": [ "limit", "offset", "total" ] } }, "required": [ "x402Version", "items", "pagination" ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Circle error code (NOT HTTP status code)", "example": 2 }, "message": { "type": "string", "description": "Error message", "example": "Invalid query parameter: maxUsdPrice must be a positive number" }, "errors": { "type": "array", "items": { "nullable": true }, "description": "Additional error details" } }, "required": [ "code", "message" ] } } } }, "503": { "description": "Discovery catalog temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Circle error code (NOT HTTP status code)", "example": 2 }, "message": { "type": "string", "description": "Error message", "example": "Invalid query parameter: maxUsdPrice must be a positive number" }, "errors": { "type": "array", "items": { "nullable": true }, "description": "Additional error details" } }, "required": [ "code", "message" ] } } } } } } }, "/v2/x402/discovery/resources": { "get": { "summary": "List discovery resources (v2)", "description": "Returns x402-compatible discovery resources with payment information and schemas.\nV2 format separates output schema from payment requirements.", "tags": [ "Discovery v2" ], "parameters": [ { "schema": { "type": "string", "description": "Fuzzy search query (searches resource URL, provider, description, categories)" }, "required": false, "description": "Fuzzy search query (searches resource URL, provider, description, categories)", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Filter by service category", "example": "PREDICTION_MARKETS" }, "required": false, "description": "Filter by service category", "name": "category", "in": "query" }, { "schema": { "type": "string", "enum": [ "http", "mcp" ], "description": "Filter by protocol type", "example": "http" }, "required": false, "description": "Filter by protocol type", "name": "type", "in": "query" }, { "schema": { "type": "string", "description": "Filter by blockchain network. Accepts CAIP-2 format (e.g., eip155:8453) or legacy SDK names (e.g., base, base-sepolia)", "example": "eip155:8453" }, "required": false, "description": "Filter by blockchain network. Accepts CAIP-2 format (e.g., eip155:8453) or legacy SDK names (e.g., base, base-sepolia)", "name": "network", "in": "query" }, { "schema": { "type": "string", "description": "Filter by payment token contract address" }, "required": false, "description": "Filter by payment token contract address", "name": "asset", "in": "query" }, { "schema": { "type": "string", "enum": [ "exact" ], "description": "Filter by payment scheme" }, "required": false, "description": "Filter by payment scheme", "name": "scheme", "in": "query" }, { "schema": { "type": "string", "description": "Filter by merchant wallet address" }, "required": false, "description": "Filter by merchant wallet address", "name": "payTo", "in": "query" }, { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Maximum price per request in USD", "example": 0.01 }, "required": false, "description": "Maximum price per request in USD", "name": "maxUsdPrice", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter by Sign-in with X support. Set to true for only SIWX endpoints, false for only non-SIWX endpoints, or omit for all endpoints", "example": false }, "required": false, "description": "Filter by Sign-in with X support. Set to true for only SIWX endpoints, false for only non-SIWX endpoints, or omit for all endpoints", "name": "siwx", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter to only endpoints that support vanilla x402 payments (non-Circle Gateway)", "example": true }, "required": false, "description": "Filter to only endpoints that support vanilla x402 payments (non-Circle Gateway)", "name": "supportsVanillax402", "in": "query" }, { "schema": { "type": "boolean", "description": "Filter to only endpoints that support Circle Gateway payments", "example": true }, "required": false, "description": "Filter to only endpoints that support Circle Gateway payments", "name": "supportsCircleGateway", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated list of fields to include in response", "example": "resource,type,accepts" }, "required": false, "description": "Comma-separated list of fields to include in response", "name": "fields", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of results to return", "example": 50 }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Number of results to skip for pagination", "example": 0 }, "required": false, "description": "Number of results to skip for pagination", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "number", "enum": [ 2 ], "description": "x402 protocol version" }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string", "format": "uri", "description": "Resource URL", "example": "https://api.example.com/v1/service" }, "type": { "type": "string", "enum": [ "http", "mcp" ], "description": "Protocol type", "example": "http" }, "x402Version": { "type": "number", "description": "x402 protocol version", "example": 2 }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string", "description": "Payment token contract address", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "network": { "type": "string", "description": "Blockchain network in CAIP-2 format", "example": "eip155:8453" }, "maxAmountRequired": { "type": "string", "description": "Maximum payment amount in atomic units", "example": "10000" }, "payTo": { "type": "string", "description": "Merchant wallet address", "example": "0x1234567890123456789012345678901234567890" }, "scheme": { "type": "string", "enum": [ "exact" ], "description": "Payment scheme" } }, "required": [ "asset", "network", "maxAmountRequired", "payTo", "scheme" ] }, "description": "Accepted payment configurations" }, "metadata": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable service name", "example": "CoinMarketCap" }, "description": { "type": "string", "description": "Service description", "example": "CoinMarketCap API endpoints" }, "category": { "type": "string", "enum": [ "SOCIAL_INTELLIGENCE", "FINANCIAL_ANALYSIS", "WEB_SEARCH_RESEARCH", "PREDICTION_MARKETS", "CREATIVE", "INFRASTRUCTURE" ], "description": "Service category", "example": "FINANCIAL_ANALYSIS" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Searchable tags", "example": [ "crypto", "market-data", "prices" ] }, "website": { "type": "string", "format": "uri", "description": "Provider website URL", "example": "https://coinmarketcap.com" }, "docsUrl": { "type": "string", "format": "uri", "description": "API documentation URL" }, "openApiUrl": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" } }, "required": [ "name", "description", "category", "tags" ] }, "path": { "type": "string", "description": "Endpoint path (relative or absolute)", "example": "/v3/cryptocurrency/quotes/latest" }, "method": { "type": "string", "description": "HTTP method", "example": "GET" }, "description": { "type": "string", "description": "Endpoint description", "example": "Get latest cryptocurrency prices" }, "mimeType": { "type": "string", "description": "Response MIME type", "example": "application/json" }, "input": { "type": "object", "additionalProperties": { "nullable": true } }, "output": { "type": "object", "additionalProperties": { "nullable": true } }, "siwx": { "type": "boolean", "description": "Whether this endpoint supports Sign-in with X authentication", "example": false }, "supportsVanillax402": { "type": "boolean", "description": "Whether this endpoint supports vanilla x402 payments (non-Circle Gateway)", "example": true }, "supportsCircleGateway": { "type": "boolean", "description": "Whether this endpoint supports Circle Gateway payments", "example": true } }, "required": [ "provider", "description" ] } }, "required": [ "resource", "type", "x402Version" ] }, "description": "List of discovered resources" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of results returned", "example": 50 }, "offset": { "type": "integer", "minimum": 0, "description": "Number of results skipped", "example": 0 }, "total": { "type": "integer", "minimum": 0, "description": "Total count of resources matching the query", "example": 42 } }, "required": [ "limit", "offset", "total" ] } }, "required": [ "x402Version", "items", "pagination" ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Circle error code (NOT HTTP status code)", "example": 2 }, "message": { "type": "string", "description": "Error message", "example": "Invalid query parameter: maxUsdPrice must be a positive number" }, "errors": { "type": "array", "items": { "nullable": true }, "description": "Additional error details" } }, "required": [ "code", "message" ] } } } }, "503": { "description": "Discovery catalog temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Circle error code (NOT HTTP status code)", "example": 2 }, "message": { "type": "string", "description": "Error message", "example": "Invalid query parameter: maxUsdPrice must be a positive number" }, "errors": { "type": "array", "items": { "nullable": true }, "description": "Additional error details" } }, "required": [ "code", "message" ] } } } } } } } } }