{
  "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 Robinhood Chain 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",
      "get_pulse_activity",
      "analyze_social_event",
      "verify_pulse_snapshot",
      "get_pulse_methodology"
    ]
  },
  "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/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, archive completeness, and immutable evidence links. Full 1h, 6h, and 24h matrices can include exact distinct-wallet and equal-window evidence. Longer default matrices degrade wallet-derived fields when their bounded evidence is unavailable. Set metrics=presses for the fast sealed-press projection used by BUYSCREENER; wallet-derived fields are then explicitly null, never zero.",
        "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": "metrics",
            "in": "query",
            "description": "For matrix view, presses returns the bounded sealed-press projection and explicitly omits wallet-derived metrics.",
            "schema": { "type": "string", "enum": ["full", "presses"], "default": "full" }
          },
          {
            "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/qed": {
      "get": {
        "operationId": "verifyStockTokenQedWitness",
        "summary": "Reconcile one stock-token corporate action across REST, Robinhood Chain, and Lean",
        "description": "Returns a read-only, hash-addressed DELL witness. The endpoint checks the official asset and corporate-action rows, the exact multiplier update event, live ERC-8056 contract state, adjusted supply, a double-application guard, and a byte-bound Lean 4 proof artifact. It fails closed when any public premise is unavailable or mismatched. Lean verifies the encoded arithmetic; it does not certify the truthfulness of an external API or RPC.",
        "responses": {
          "200": {
            "description": "Q.E.D. receipt; inspect the state and per-premise checks",
            "headers": {
              "X-QED-State": {
                "description": "Overall proof-machine verdict",
                "schema": { "type": "string", "enum": ["qed", "refused"] }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["schemaVersion", "state", "readOnly", "asset", "corporateAction", "chain", "proof", "checks", "receiptHash"],
                  "properties": {
                    "schemaVersion": { "type": "string", "const": "1.0.0" },
                    "state": { "type": "string", "enum": ["qed", "refused"] },
                    "readOnly": { "type": "boolean", "const": true },
                    "receiptHash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
                    "asset": { "type": "object", "additionalProperties": true },
                    "corporateAction": { "type": "object", "additionalProperties": true },
                    "chain": { "type": "object", "additionalProperties": true },
                    "proof": { "type": "object", "additionalProperties": true },
                    "checks": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
                    "limits": { "type": "object", "additionalProperties": { "type": "string" } }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "503": {
            "description": "A public proof input could not be reconciled; no receipt was issued"
          }
        }
      },
      "head": {
        "operationId": "inspectStockTokenQedWitness",
        "summary": "Run the proof machine without returning the receipt body",
        "responses": {
          "200": { "description": "The witness reconciled; inspect X-QED-State" },
          "503": { "description": "The proof machine refused" }
        }
      }
    },
    "/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/v1/stock-history": {
      "get": {
        "operationId": "getRobinhoodChainStockPulseHistory",
        "summary": "Read persistent Stock Button activity",
        "description": "Returns bounded, server-side rollups of classified Robinhood Chain stock-token buys. Five-minute aggregates are append-only; inactive assets do not produce dense zero rows. Buyer observations are summed five-minute unique counts, not a claimed range-wide distinct-wallet count. The response includes at most eight recent exact events.",
        "parameters": [
          {
            "name": "range",
            "in": "query",
            "schema": { "type": "string", "enum": ["1h", "6h", "24h", "7d", "30d"], "default": "24h" }
          },
          {
            "name": "view",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "const": "matrix", "default": "matrix" }
          }
        ],
        "responses": {
          "200": {
            "description": "Persistent Stock Button aggregate matrix and bounded recent evidence",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": { "description": "Unsupported range or view" },
          "503": { "description": "Stock Archive storage is temporarily unavailable" }
        }
      },
      "head": {
        "operationId": "inspectStockPulseHistoryApi",
        "summary": "Inspect Stock Archive history API availability",
        "responses": {
          "200": { "description": "Endpoint is available" },
          "400": { "description": "Unsupported range or view" }
        }
      }
    },
    "/api/v1/stock-snapshots/{hash}": {
      "get": {
        "operationId": "getVerifiedStockPulseSnapshot",
        "summary": "Read an immutable Stock Archive 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 Stock Button evidence snapshot, with exact events bounded to 500",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": { "description": "Invalid snapshot hash" },
          "404": { "description": "Snapshot not found" },
          "503": { "description": "Stock Archive 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" }
              }
            }
          }
        }
      }
    }
  }
}