{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Bazaar",
    "version": "0.6.0",
    "description": "Open, permissionless marketplace and discovery layer for AI agents — APIs, MCP tools, datasets and x402-payable services. No account or API key required for any read endpoint. Wire-compatible with Coinbase's CDP x402 Bazaar API. Built by Saylor Innovations."
  },
  "servers": [{ "url": "https://bazaar.saylorinnovations.com" }],
  "paths": {
    "/submit": {
      "post": {
        "operationId": "submitListing",
        "summary": "List (or refresh) a resource by its x402 manifest URL",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["manifestUrl"],
                "properties": {
                  "manifestUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "HTTPS URL of a public x402 manifest (e.g. /.well-known/x402.json)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Listed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "host": { "type": "string" },
                    "resourceCount": { "type": "integer" }
                  }
                }
              }
            }
          },
          "422": { "description": "Manifest fetch or validation failed" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/discovery/search": {
      "get": {
        "operationId": "searchResources",
        "summary": "Keyword and filter search across all listed resources",
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Free-text keyword search" },
          { "name": "network", "in": "query", "schema": { "type": "string" }, "description": "e.g. eip155:8453, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" },
          { "name": "asset", "in": "query", "schema": { "type": "string" } },
          { "name": "scheme", "in": "query", "schema": { "type": "string" } },
          { "name": "payTo", "in": "query", "schema": { "type": "string" } },
          { "name": "urlSubstring", "in": "query", "schema": { "type": "string" } },
          { "name": "maxUsdPrice", "in": "query", "schema": { "type": "number" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Matching resources",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          }
        }
      }
    },
    "/discovery/resources": {
      "get": {
        "operationId": "listResources",
        "summary": "Paginated listing of every indexed resource, ranked by 30-day call volume (or recency)",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["popular", "recent"], "default": "popular" }, "description": "'recent' orders by newest listing first; default ranks by 30-day call volume." }
        ],
        "responses": {
          "200": {
            "description": "A page of resources",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcesPage" } } }
          }
        }
      }
    },
    "/discovery/saylor": {
      "get": {
        "operationId": "listSaylorOfficial",
        "summary": "Quota-resistant listing of verified Saylor Innovations x402 endpoints from the live Saylor manifest and service index",
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string" } },
          { "name": "family", "in": "query", "schema": { "type": "string" }, "description": "Endpoint family such as evm, solana, research, package, market, kb, or guide." },
          { "name": "resourceType", "in": "query", "schema": { "type": "string" } },
          { "name": "tag", "in": "query", "schema": { "type": "string" } },
          { "name": "network", "in": "query", "schema": { "type": "string" } },
          { "name": "asset", "in": "query", "schema": { "type": "string" } },
          { "name": "scheme", "in": "query", "schema": { "type": "string" } },
          { "name": "payTo", "in": "query", "schema": { "type": "string" } },
          { "name": "maxUsdPrice", "in": "query", "schema": { "type": "number" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Verified Saylor official resources",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaylorOfficialResponse" } } }
          }
        }
      }
    },
    "/discovery/merchant": {
      "get": {
        "operationId": "merchantResources",
        "summary": "All resources that pay a specific address",
        "parameters": [
          { "name": "payTo", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Resources paying this address",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          },
          "400": { "description": "Missing payTo parameter" }
        }
      }
    },
    "/discovery/facets": {
      "get": {
        "operationId": "getDiscoveryFacets",
        "summary": "Compact filter-planning counts for networks, assets, schemes, resource types, providers, price bands, liveness and trust states",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 }, "description": "Maximum number of values to return for ranked facet lists." }
        ],
        "responses": {
          "200": {
            "description": "Discovery facets",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetsResponse" } } }
          }
        }
      }
    },
    "/discovery/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Catalog-wide totals: listings, resources, accepts, merchants, network count, calls. Pass full=1 for the per-network/per-source breakdown (a full table scan — opt-in on purpose).",
        "parameters": [
          { "name": "full", "in": "query", "schema": { "type": "string", "enum": ["1"] }, "description": "Include byNetwork/bySource breakdowns." }
        ],
        "responses": {
          "200": {
            "description": "Aggregate stats",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } }
          }
        }
      }
    },
    "/discovery.json": {
      "get": {
        "operationId": "getMachineDiscoveryManifest",
        "summary": "Machine-readable map of Agent Bazaar discovery surfaces, schemas, MCP entry point, and Saylor official listings",
        "responses": {
          "200": {
            "description": "Machine discovery manifest",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryManifest" } } }
          }
        }
      }
    },
    "/resources/{slug}": {
      "get": {
        "operationId": "getResourcePage",
        "summary": "Human-readable detail page for one resource",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "HTML page", "content": { "text/html": {} } }, "404": { "description": "Not found" } }
      }
    },
    "/resources/{slug}.json": {
      "get": {
        "operationId": "getResourceRecord",
        "summary": "Machine-readable twin of the resource detail page",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Full resource record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/providers/{host}": {
      "get": {
        "operationId": "getProviderPage",
        "summary": "All resources published by a given provider host",
        "parameters": [{ "name": "host", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "HTML page listing the provider's resources" }, "404": { "description": "Not found" } }
      }
    },
    "/submit-agent": {
      "post": {
        "operationId": "submitAgent",
        "summary": "Register (or refresh) an A2A agent by its agent card URL",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agentCardUrl"],
                "properties": { "agentCardUrl": { "type": "string", "format": "uri", "description": "HTTPS URL of a public A2A agent card, e.g. /.well-known/agent-card.json" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "slug": { "type": "string" }, "host": { "type": "string" }, "name": { "type": "string" } } } } } },
          "422": { "description": "Card fetch or validation failed" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/discovery/agents": {
      "get": {
        "operationId": "discoverAgents",
        "summary": "Search or list the A2A agent registry",
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": { "200": { "description": "Agent list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } } } } }
      }
    },
    "/agents/{slug}": {
      "get": {
        "operationId": "getAgentPage",
        "summary": "Human-readable detail page for one registered agent",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "HTML page" }, "404": { "description": "Not found" } }
      }
    },
    "/agents/{slug}.json": {
      "get": {
        "operationId": "getAgentRecord",
        "summary": "Machine-readable twin of the agent detail page (the full agent card as submitted)",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Full agent record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/categories": {
      "get": { "operationId": "listCategories", "summary": "Browse resource categories with counts", "responses": { "200": { "description": "HTML page" } } }
    },
    "/categories/{category}": {
      "get": {
        "operationId": "getCategoryPage",
        "summary": "Resources of a given type (paginated)",
        "parameters": [{ "name": "category", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "HTML page" }, "404": { "description": "No resources in this category" } }
      }
    },
    "/networks": {
      "get": { "operationId": "listNetworks", "summary": "Browse networks with counts", "responses": { "200": { "description": "HTML page" } } }
    },
    "/networks/{network}": {
      "get": {
        "operationId": "getNetworkPage",
        "summary": "Resources accepting payment on a given CAIP-2 network (paginated)",
        "parameters": [{ "name": "network", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "HTML page" }, "404": { "description": "No resources on this network" } }
      }
    },
    "/guides": {
      "get": { "operationId": "listGuides", "summary": "Browse the guides library", "responses": { "200": { "description": "HTML page" } } }
    },
    "/guides.json": {
      "get": { "operationId": "listGuidesJson", "summary": "Machine-readable list of every guide (slug, title, description, category, readMins)", "responses": { "200": { "description": "Guide list", "content": { "application/json": { "schema": { "type": "object", "properties": { "guides": { "type": "array", "items": { "type": "object" } } } } } } } } }
    },
    "/guides/{slug}": {
      "get": {
        "operationId": "getGuidePage",
        "summary": "One in-depth guide",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "HTML page" }, "404": { "description": "Not found" } }
      }
    },
    "/guides/{slug}.json": {
      "get": {
        "operationId": "getGuideRecord",
        "summary": "Plain-text machine twin of a guide (HTML stripped)",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Guide text", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "related": { "type": "array", "items": { "type": "string" } } } } } } },
          "404": { "description": "Not found" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Accepts": {
        "type": "object",
        "properties": {
          "scheme": { "type": "string" },
          "network": { "type": "string" },
          "payTo": { "type": "string" },
          "asset": { "type": "string" },
          "amount": { "type": "string" },
          "amountUsd": { "type": "number" },
          "maxTimeoutSeconds": { "type": "integer" }
        }
      },
      "Quality": {
        "type": "object",
        "description": "Additive trust/popularity signal, not part of the base x402 wire shape.",
        "properties": {
          "calls30d": { "type": "integer" },
          "uniquePayers30d": { "type": "integer" },
          "lastCalledAt": { "type": "string", "format": "date-time" }
        }
      },
      "Resource": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "slug": { "type": "string" },
          "resource": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "type": { "type": "string" },
          "serviceName": { "type": "string", "description": "Human-readable service family, matching Coinbase Bazaar-style resource records when supplied." },
          "mimeType": { "type": "string", "description": "Primary response MIME type; Saylor official endpoints use application/json." },
          "iconUrl": { "type": "string", "format": "uri", "description": "Provider or service icon for agent catalogs." },
          "resourceType": { "type": "string" },
          "x402Version": { "type": "integer" },
          "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/Accepts" } },
          "outputSchema": { "type": "object" },
          "extensions": { "type": "object", "description": "Protocol-specific discovery extensions, including extensions.bazaar.info and extensions.bazaar.schema for agent-readable input/output examples." },
          "tags": { "type": "array", "items": { "type": "string" } },
          "sourceHost": { "type": "string" },
          "lastUpdated": { "type": "string", "format": "date-time" },
          "quality": { "$ref": "#/components/schemas/Quality" },
          "metadata": { "$ref": "#/components/schemas/ResourceMetadata" },
          "liveness": {
            "type": "object",
            "description": "Only populated for owner-submitted resources — see scripts/check-liveness.mjs.",
            "properties": {
              "isLive": { "type": "boolean", "description": "Absent/undefined if never checked; false means the endpoint did not respond on its last check." },
              "lastCheckedAt": { "type": "string", "format": "date-time" }
            }
          },
          "verified": { "type": "boolean", "description": "True only when the provider proved control of this listing via POST /submit." }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer" },
          "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } },
          "partialResults": { "type": "boolean" },
          "searchMethod": { "type": "string" }
        }
      },
      "ResourceMetadata": {
        "type": "object",
        "description": "Agent-first fields. Saylor official listings include these consistently; mirrored third-party resources include only what their provider supplied.",
        "properties": {
          "method": { "type": "string", "description": "HTTP method, usually GET for listed Saylor endpoints." },
          "serviceName": { "type": "string" },
          "mimeType": { "type": "string" },
          "iconUrl": { "type": "string", "format": "uri" },
          "extensions": { "type": "object" },
          "inputMimeTypes": { "type": "array", "items": { "type": "string" } },
          "outputMimeTypes": { "type": "array", "items": { "type": "string" } },
          "paymentProtocol": { "type": "string", "enum": ["x402"] },
          "noAccountRequired": { "type": "boolean" },
          "noApiKeyRequired": { "type": "boolean" },
          "auth": { "type": "string" },
          "pricingPolicy": { "type": "object", "properties": { "unit": { "type": "string" }, "minimumUsd": { "type": "number" } } },
          "parameters": { "type": "array", "items": { "type": "object" } },
          "exampleUrl": { "type": "string", "format": "uri" },
          "discoveryUrl": { "type": "string", "format": "uri" },
          "capabilities": { "type": "array", "items": { "type": "string" } },
          "useWhen": { "type": "string" },
          "doNotUseWhen": { "type": "string" },
          "sideEffects": { "type": "string" },
          "license": { "type": "string" },
          "repository": { "type": "string", "format": "uri" },
          "family": { "type": "string" }
        }
      },
      "DiscoveryManifest": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "provider": { "type": "string" },
          "version": { "type": "string" },
          "baseUrl": { "type": "string", "format": "uri" },
          "protocols": { "type": "array", "items": { "type": "string" } },
          "agentUse": { "type": "object" },
          "endpoints": { "type": "array", "items": { "type": "object" } },
          "schemas": { "type": "object" },
          "saylorOfficialListings": { "type": "object" }
        }
      },
      "ResourcesPage": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer" },
          "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } },
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "SaylorOfficialResponse": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer" },
          "provider": { "type": "object" },
          "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } },
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "source": { "type": "string" },
          "filters": { "type": "object" }
        }
      },
      "FacetValue": {
        "type": "object",
        "properties": {
          "value": { "type": "string" },
          "count": { "type": "integer" }
        }
      },
      "FacetsResponse": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer" },
          "limit": { "type": "integer" },
          "facets": {
            "type": "object",
            "properties": {
              "networks": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } },
              "assets": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } },
              "schemes": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } },
              "resourceTypes": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } },
              "providers": { "type": "array", "items": { "$ref": "#/components/schemas/FacetValue" } },
              "priceBands": { "type": "object", "additionalProperties": { "type": "integer" } },
              "liveness": { "type": "object", "additionalProperties": { "type": "integer" } },
              "trust": { "type": "object", "additionalProperties": { "type": "integer" } }
            }
          },
          "note": { "type": "string" },
          "fallback": { "type": "string" },
          "warning": { "type": "string" }
        }
      },
      "Agent": {
        "type": "object",
        "description": "An A2A agent registered in the directory (a different entity than an x402 resource — no inherent payment model).",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "host": { "type": "string" },
          "cardUrl": { "type": "string", "format": "uri" },
          "provider": { "type": "object", "properties": { "organization": { "type": "string" }, "url": { "type": "string" } } },
          "version": { "type": "string" },
          "protocolVersion": { "type": "string" },
          "documentationUrl": { "type": "string" },
          "skills": { "type": "array", "items": { "type": "object" } },
          "capabilities": { "type": "object" },
          "inputModes": { "type": "array", "items": { "type": "string" } },
          "outputModes": { "type": "array", "items": { "type": "string" } },
          "liveness": { "type": "object", "properties": { "isLive": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "format": "date-time" } } }
        }
      },
      "Stats": {
        "type": "object",
        "description": "byNetwork/bySource are only included when the request includes full=1 — each is a full, unfiltered GROUP BY scan, so it is opt-in rather than computed on every call.",
        "properties": {
          "listings": { "type": "integer" },
          "resources": { "type": "integer" },
          "accepts": { "type": "integer" },
          "merchants": { "type": "integer" },
          "networks": { "type": "integer", "description": "Distinct network count. Cheap — included even without full=1." },
          "calls30d": { "type": "integer" },
          "byNetwork": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Only present with ?full=1." },
          "bySource": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Only present with ?full=1." }
        }
      }
    }
  }
}
