{
  "openapi": "3.1.0",
  "info": {
    "title": "Keryx API",
    "version": "0.1.0",
    "description": "Paid tool registry for AI agents. Discovery, pricing, and execution over x402 with USDC settlement on Arc."
  },
  "servers": [
    { "url": "https://keryxhq.xyz" }
  ],
  "paths": {
    "/.well-known/x402": {
      "get": {
        "summary": "x402 discovery manifest",
        "description": "Machine-readable catalog of free surfaces and paid /api/call tools for agent discovery.",
        "responses": {
          "200": { "description": "Discovery JSON (version, freeResources, paid_routes, network)" }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "LLM-oriented site map",
        "description": "Plain-text map of free and paid endpoints for LLM agents.",
        "responses": {
          "200": { "description": "text/plain catalog" }
        }
      }
    },
    "/api/tools": {
      "get": {
        "summary": "List all tools",
        "description": "Returns every published tool with price, schema, and metadata. Agents use this for discovery.",
        "responses": {
          "200": {
            "description": "Array of tool definitions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ToolDefinition" }
                }
              }
            }
          }
        }
      }
    },
    "/api/call": {
      "post": {
        "summary": "Quote + execute a tool (x402)",
        "description": "First call without X-PAYMENT returns 402 with requirements (includes extensions.bazaar). Retry with signed payload to execute and settle.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "toolId": { "type": "string" },
                  "args": { "type": "object" }
                },
                "required": ["toolId"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Result + settlement info" },
          "402": { "description": "Payment required — includes accepts requirements + bazaar extensions" }
        }
      }
    },
    "/api/demo": {
      "get": {
        "summary": "Free sample before pay",
        "description": "Runs a seeded tool with sampleArgs and returns the response shape without charging USDC. Query: toolId.",
        "parameters": [
          {
            "name": "toolId",
            "in": "query",
            "schema": { "type": "string", "default": "crypto.price" }
          }
        ],
        "responses": {
          "200": { "description": "Free sample result + paid-path preview" }
        }
      }
    },
    "/api/receipt/verify": {
      "post": {
        "summary": "Verify a settlement receipt",
        "description": "Look up a public ledger entry by id or txHash. Returns proof tier R0–R5 (R5 = Arc eth_getTransactionReceipt success) + Arcscan link.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "txHash": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Receipt classification" },
          "404": { "description": "Not in ledger window" }
        }
      },
      "get": {
        "summary": "Receipt verify docs",
        "responses": { "200": { "description": "Tier legend + body shape" } }
      }
    },
    "/api/mcp": {
      "post": {
        "summary": "MCP JSON-RPC endpoint",
        "description": "Model Context Protocol server. Use for native tool use from Claude Code, Cursor, etc. Config: {\"mcpServers\":{\"keryx\":{\"type\":\"http\",\"url\":\"https://keryxhq.xyz/api/mcp\"}}}",
        "responses": {
          "200": { "description": "JSON-RPC response" }
        }
      }
    },
    "/api/publishers/tools": {
      "post": {
        "summary": "Publish or update a tool (EIP-191 signed)",
        "responses": {
          "200": { "description": "Tool registered" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolDefinition": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "summary": { "type": "string" },
          "priceUsd": { "type": "number" },
          "publisherName": { "type": "string" },
          "args": { "type": "object" },
          "verified": { "type": "boolean" }
        }
      }
    }
  }
}