{
  "openapi": "3.1.0",
  "info": {
    "title": "Bitcoin Cartoons Agent Commerce API",
    "version": "2026-08-25",
    "summary": "Universal Commerce Protocol (UCP) endpoint for AI agents shopping at Bitcoin Cartoons.",
    "description": "Bitcoin Cartoons (https://bitcoincartoons.io) sells hand-drawn bitcoin cartoons as shirts, hats, framed prints, stickers and original art. Agents interact with the store through a single JSON-RPC 2.0 endpoint that speaks MCP (Model Context Protocol) and implements the Universal Commerce Protocol. Discover tools with the `tools/list` method. Catalog search works without a token; checkout and order tools use OAuth 2.0 with the scopes listed below. Human-readable agent instructions: https://bitcoincartoons.io/agents.md",
    "contact": { "name": "Bitcoin Cartoons", "email": "sales@bitcoincartoons.io", "url": "https://bitcoincartoons.io/pages/contact" }
  },
  "externalDocs": { "description": "Agent instructions (agents.md)", "url": "https://bitcoincartoons.io/agents.md" },
  "servers": [ { "url": "https://bitcoincartoons.io" } ],
  "tags": [ { "name": "ucp", "description": "Universal Commerce Protocol over MCP (JSON-RPC 2.0)" } ],
  "paths": {
    "/.well-known/ucp": {
      "get": {
        "tags": ["ucp"],
        "operationId": "getUcpProfile",
        "summary": "UCP merchant profile (supported versions, services, capabilities, payment handlers)",
        "security": [ {} ],
        "responses": {
          "200": { "description": "UCP discovery document", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/api/ucp/mcp": {
      "post": {
        "tags": ["ucp"],
        "operationId": "callUcpMcp",
        "summary": "Send a JSON-RPC 2.0 / MCP request (initialize, tools/list, tools/call)",
        "description": "Available tools include search_catalog, lookup_catalog, get_product, create_cart, get_cart, update_cart, cancel_cart, create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout and get_order. Tool input schemas are returned by tools/list. Method schema: https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json",
        "security": [ {}, { "shopifyCustomerOAuth": ["dev.ucp.shopping.catalog.search:read", "dev.ucp.shopping.checkout:manage"] } ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcRequest" },
              "examples": {
                "listTools": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } },
                "searchCatalog": { "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "search_catalog", "arguments": { "query": "bitcoin shirt" } } } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response. Errors (invalid JSON, unknown method, bad params) are returned as a JSON `error` object, not HTML.",
            "content": {
              "application/json": {
                "schema": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcSuccess" }, { "$ref": "#/components/schemas/JsonRpcError" } ] },
                "examples": {
                  "methodNotFound": { "value": { "jsonrpc": "2.0", "id": 1, "error": { "code": -32601, "message": "Method not found", "data": "nope" } } },
                  "invalidJson": { "value": { "jsonrpc": "2.0", "id": 0, "error": { "code": -32600, "message": "Invalid Request", "data": "Invalid JSON in request body." } } }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "shopifyCustomerOAuth": {
        "type": "oauth2",
        "description": "Shopify customer-account OAuth 2.0 (authorization code + PKCE S256). Metadata: https://bitcoincartoons.io/.well-known/oauth-authorization-server and https://bitcoincartoons.io/.well-known/oauth-protected-resource",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://shopify.com/authentication/78513275180/oauth/authorize",
            "tokenUrl": "https://shopify.com/authentication/78513275180/oauth/token",
            "scopes": {
              "openid": "OpenID Connect sign-in",
              "email": "Read the customer's email address",
              "dev.ucp.shopping.catalog.search:read": "Search and read the product catalog",
              "dev.ucp.shopping.checkout:manage": "Create, update, complete and cancel carts and checkouts for the customer",
              "customer-account-api:full": "Full access to the customer's account (orders, addresses)",
              "customer-account-mcp-api:full": "Full access to the customer account MCP tools"
            }
          }
        }
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["integer", "string"] },
          "method": { "type": "string", "examples": ["initialize", "tools/list", "tools/call"] },
          "params": { "type": "object" }
        }
      },
      "JsonRpcSuccess": {
        "type": "object",
        "required": ["jsonrpc", "id", "result"],
        "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": ["integer", "string"] }, "result": { "type": "object" } }
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["jsonrpc", "id", "error"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["integer", "string", "null"] },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "integer", "description": "-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error" },
              "message": { "type": "string" },
              "data": {}
            }
          }
        }
      }
    }
  }
}