{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Bazaar",
    "version": "0.4.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/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/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Catalog-wide totals: listings, resources, accepts, merchants, calls, network breakdown",
        "responses": {
          "200": {
            "description": "Aggregate stats",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } }
          }
        }
      }
    },
    "/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" } }
      }
    }
  },
  "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" },
          "resourceType": { "type": "string" },
          "x402Version": { "type": "integer" },
          "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/Accepts" } },
          "outputSchema": { "type": "object" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "sourceHost": { "type": "string" },
          "lastUpdated": { "type": "string", "format": "date-time" },
          "quality": { "$ref": "#/components/schemas/Quality" },
          "metadata": { "type": "object", "description": "Agent-first fields (capabilities, useWhen, doNotUseWhen, license, repository, …), only present when the provider supplied them." },
          "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" }
        }
      },
      "ResourcesPage": {
        "type": "object",
        "properties": {
          "x402Version": { "type": "integer" },
          "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } },
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "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",
        "properties": {
          "listings": { "type": "integer" },
          "resources": { "type": "integer" },
          "accepts": { "type": "integer" },
          "merchants": { "type": "integer" },
          "calls30d": { "type": "integer" },
          "byNetwork": { "type": "object", "additionalProperties": { "type": "integer" } },
          "bySource": { "type": "object", "additionalProperties": { "type": "integer" } }
        }
      }
    }
  }
}