{
  "openapi": "3.1.1",
  "info": {
    "title": "Off-Switch Index Route API",
    "version": "1.0.0",
    "description": "Read-only Robinhood Chain pool discovery and Uniswap V3 route simulations. The compact representation is the default and is designed for agents, bots, and scripts.",
    "license": {
      "name": "Public read-only API"
    }
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://www.hoodbuybutton.com"
    }
  ],
  "externalDocs": {
    "description": "Developer documentation and usage policy",
    "url": "https://www.hoodbuybutton.com/developers/"
  },
  "x-mcp": {
    "name": "com.hoodbuybutton/route-intelligence",
    "title": "Buy Button Route Intelligence",
    "transport": "streamable-http",
    "url": "https://www.hoodbuybutton.com/mcp",
    "manifest": "https://www.hoodbuybutton.com/server.json",
    "readOnly": true,
    "tools": [
      "resolve_community_token",
      "list_community_tokens",
      "get_route_quote",
      "compare_community_routes"
    ]
  },
  "paths": {
    "/api/v1/routes": {
      "get": {
        "operationId": "mapRobinhoodChainRoutes",
        "summary": "Discover pools and simulate buy routes",
        "description": "Returns ranked pools for a Robinhood Chain ERC-20 contract. Quotes are read-only estimates and do not connect a wallet, approve tokens, or execute transactions.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "description": "Robinhood Chain ERC-20 contract. Defaults to BUY.",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$",
              "default": "0x0e8720B8cD84F95b4b6696adbFA8063c4B8B94F2"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "description": "Simulated USD buy size.",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 100000,
              "default": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum ranked pools to inspect and return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 6
            }
          },
          {
            "name": "view",
            "in": "query",
            "description": "Compact is stable and token-efficient. Full includes raw evidence used by the website.",
            "schema": {
              "type": "string",
              "enum": ["compact", "full"],
              "default": "compact"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pool map and route quote",
            "headers": {
              "ETag": {
                "description": "Validator for conditional requests",
                "schema": { "type": "string" }
              },
              "Link": {
                "description": "API catalog, OpenAPI, schema, documentation, and health discovery links",
                "schema": { "type": "string" }
              },
              "X-API-Version": {
                "schema": { "type": "string", "const": "1.0.0" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    { "$ref": "https://www.hoodbuybutton.com/schemas/off-switch-index-v1.json" },
                    { "type": "object", "description": "Full evidence representation", "additionalProperties": true }
                  ]
                }
              }
            }
          },
          "304": {
            "description": "The representation matches If-None-Match"
          },
          "400": {
            "$ref": "#/components/responses/Problem"
          },
          "405": {
            "$ref": "#/components/responses/Problem"
          },
          "502": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "head": {
        "operationId": "inspectRouteApi",
        "summary": "Inspect route API availability and discovery headers",
        "responses": {
          "200": { "description": "Endpoint is available" },
          "405": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/v1/badge": {
      "get": {
        "operationId": "renderRobinhoodChainRouteBadge",
        "summary": "Render an embeddable live route-state badge",
        "description": "Returns a cache-aware SVG showing ON, THIN, or UNKNOWN route state for the selected Robinhood Chain token and USD size.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "description": "Robinhood Chain ERC-20 contract. Defaults to BUY.",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$",
              "default": "0x0e8720B8cD84F95b4b6696adbFA8063c4B8B94F2"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "description": "Simulated USD buy size represented by the badge.",
            "schema": { "type": "number", "minimum": 1, "maximum": 100000, "default": 100 }
          }
        ],
        "responses": {
          "200": {
            "description": "Live SVG route-state badge",
            "content": { "image/svg+xml": { "schema": { "type": "string", "contentMediaType": "image/svg+xml" } } }
          },
          "400": { "description": "Invalid contract or amount, represented as an SVG error badge" },
          "405": { "description": "Method not allowed" }
        }
      }
    },
    "/api/v1/directory": {
      "get": {
        "operationId": "mapCuratedRobinhoodChainDirectory",
        "summary": "Collect live routes for the curated community registry",
        "description": "Returns partial-safe compact route evidence for every contract in the public community registry using one cacheable request.",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "description": "Simulated USD buy size applied to every listed contract.",
            "schema": { "type": "number", "minimum": 1, "maximum": 100000, "default": 100 }
          }
        ],
        "responses": {
          "200": { "description": "Aggregate directory route evidence", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "400": { "description": "Invalid amount" },
          "502": { "description": "No live contract evidence could be collected" }
        }
      }
    },
    "/api/v1/presses": {
      "get": {
        "operationId": "getRobinhoodChainBuyPulse",
        "summary": "Compare live Robinhood Chain buy activity by community",
        "description": "Returns rolling buy counts grouped by curated community token, twelve exact five-minute history buckets, and an explorer-linked live button tape. A buy is an indexed transaction, not proof of one individual human.",
        "responses": {
          "200": {
            "description": "Live community buy activity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["generatedAt", "chain", "definition", "summary", "coverage", "tokens", "history", "tape"],
                  "properties": {
                    "generatedAt": { "type": "string", "format": "date-time" },
                    "chain": { "type": "object", "additionalProperties": true },
                    "definition": { "type": "object", "additionalProperties": { "type": "string" } },
                    "summary": { "type": "object", "additionalProperties": true },
                    "coverage": { "type": "object", "additionalProperties": true },
                    "tokens": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
                    "history": { "type": "object", "additionalProperties": true },
                    "tape": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
                  }
                }
              }
            }
          },
          "502": { "description": "Live buy activity could not be collected" }
        }
      },
      "head": {
        "operationId": "inspectBuyPulseApi",
        "summary": "Inspect BUY Pulse feed availability",
        "responses": {
          "200": { "description": "Endpoint is available" }
        }
      }
    },
    "/api/v1/history": {
      "get": {
        "operationId": "getRobinhoodChainBuyPulseHistory",
        "summary": "Read persistent five-minute Robinhood Chain buy history",
        "description": "Returns append-only five-minute ecosystem or community buckets. Matrix view adds bounded rollups, exact distinct onchain wallets, acceleration, archive completeness, and immutable evidence links.",
        "parameters": [
          {
            "name": "range",
            "in": "query",
            "schema": { "type": "string", "enum": ["1h", "6h", "24h", "7d", "30d"], "default": "24h" }
          },
          {
            "name": "view",
            "in": "query",
            "description": "Use matrix for chart-ready ecosystem and per-token history with server-side rollups.",
            "schema": { "type": "string", "enum": ["matrix"] }
          },
          {
            "name": "token",
            "in": "query",
            "description": "Optional community slug, symbol, or contract address.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Persistent five-minute BUY Pulse history",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "503": { "description": "History storage is temporarily unavailable" }
        }
      },
      "head": {
        "operationId": "inspectBuyPulseHistoryApi",
        "summary": "Inspect persistent history API availability",
        "responses": { "200": { "description": "Endpoint is available" } }
      }
    },
    "/api/v1/snapshots/{hash}": {
      "get": {
        "operationId": "getVerifiedBuyPulseSnapshot",
        "summary": "Read an immutable BUY Pulse snapshot by SHA-256 hash",
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Hash-addressed five-minute evidence snapshot",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": { "description": "Invalid snapshot hash" },
          "404": { "description": "Snapshot not found" },
          "503": { "description": "Snapshot storage is temporarily unavailable" }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getRouteApiHealth",
        "summary": "Check API process health without querying market providers",
        "responses": {
          "200": {
            "description": "API process is available",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["status", "apiVersion", "chainId", "generatedAt", "links"],
                  "properties": {
                    "status": { "type": "string", "const": "ok" },
                    "apiVersion": { "type": "string", "const": "1.0.0" },
                    "chainId": { "type": "integer", "const": 4663 },
                    "generatedAt": { "type": "string", "format": "date-time" },
                    "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Problem": {
        "description": "Machine-readable request or upstream problem",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/Problem" }
          }
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "required": ["type", "title", "status", "detail", "instance"],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer", "minimum": 400, "maximum": 599 },
          "detail": { "type": "string" },
          "instance": { "type": "string", "format": "uri" },
          "invalidParams": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "reason"],
              "properties": {
                "name": { "type": "string" },
                "reason": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}