{
  "openapi": "3.1.0",
  "info": {
    "title": "Bloom Intelligence API",
    "version": "1.0.0",
    "description": "Read-only intelligence for Base: Oracle (token recommendation), Security (token risk), and Copilot (analyst reasoning). No signing, swaps, or fund movement.",
    "x-disclaimer": "Intelligence and signals only. Not financial advice; no guaranteed outcome."
  },
  "servers": [{ "url": "https://www.bloomterminal.io", "description": "Production" }],
  "security": [{ "ApiKeyAuth": [] }],
  "tags": [
    { "name": "Oracle" },
    { "name": "Security" },
    { "name": "Copilot" }
  ],
  "paths": {
    "/api/partner/v1/oracle": {
      "post": {
        "tags": ["Oracle"],
        "summary": "Analyze a Base token",
        "description": "Returns recommendation (BUY/WATCH/REJECT) with confidence, conviction, risk, forecast, and reasoning. Scope: oracle.",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OracleRequest" } } }
        },
        "responses": {
          "200": { "description": "Analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OracleEnvelope" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/partner/v1/security": {
      "post": {
        "tags": ["Security"],
        "summary": "Assess a Base token's security",
        "description": "Returns securityScore (0-100, higher = safer), riskLevel, holderConcentration, checks, and a summary. Scope: security.",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityRequest" } } }
        },
        "responses": {
          "200": { "description": "Security assessment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityEnvelope" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/partner/v1/copilot": {
      "post": {
        "tags": ["Copilot"],
        "summary": "Ask Bloom Copilot",
        "description": "Structured analyst response. Select model: mimo (Fast Reasoning) or anthropic (Claude Fable 5 · Deep Reasoning). Scope: copilot.",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotRequest" } } }
        },
        "responses": {
          "200": { "description": "Copilot response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotEnvelope" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "description": "Reasoning layer unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as 'Authorization: Bearer bloom_pk_live_<id>.<secret>'. The 'x-api-key' header is also accepted."
      }
    },
    "schemas": {
      "OracleRequest": {
        "type": "object",
        "required": ["token"],
        "properties": {
          "token": { "type": "string", "description": "Base token address (0x…40 hex)", "example": "0x4200000000000000000000000000000000000006" },
          "chain": { "type": "string", "enum": ["base"], "default": "base" }
        }
      },
      "SecurityRequest": {
        "type": "object",
        "required": ["token"],
        "properties": {
          "token": { "type": "string", "example": "0x4200000000000000000000000000000000000006" },
          "chain": { "type": "string", "enum": ["base"], "default": "base" },
          "summary": { "type": "boolean", "default": true, "description": "Include an AI summary when the reasoning layer is configured." }
        }
      },
      "CopilotRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "maxLength": 4000, "example": "Summarize the risk profile of this token." },
          "model": { "type": "string", "enum": ["mimo", "anthropic"], "description": "mimo = Fast Reasoning; anthropic = Claude Fable 5 · Deep Reasoning." },
          "context": { "type": "object", "additionalProperties": true, "description": "Optional read-only context (e.g. currentVault, currentApy, positionValueUsd)." }
        }
      },
      "Envelope": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "requestId": { "type": "string" },
          "usage": { "type": "object", "properties": { "model": { "type": "string" }, "rateLimit": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetAt": { "type": "integer" } } } } },
          "latencyMs": { "type": "integer" },
          "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }
        }
      },
      "ErrorEnvelope": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "ok": { "const": false } } }] },
      "OracleData": {
        "type": "object",
        "properties": {
          "token": { "type": "object" },
          "recommendation": { "type": "string", "enum": ["BUY", "WATCH", "REJECT"] },
          "confidence": { "type": "number" },
          "conviction": { "type": ["number", "null"] },
          "consensus": { "type": "object", "properties": { "buy": { "type": "integer" }, "watch": { "type": "integer" }, "reject": { "type": "integer" }, "population": { "type": "integer" } } },
          "risk": { "type": "object", "properties": { "level": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH"] }, "score": { "type": "number" } } },
          "forecast": { "type": "object", "properties": { "upsidePct": { "type": "number" }, "downsidePct": { "type": "number" }, "confidencePct": { "type": "number" }, "horizonHours": { "type": "number" } } },
          "reasoning": { "type": "object", "properties": { "provider": { "type": "string" }, "summary": { "type": "string" }, "bullish": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "array", "items": { "type": "string" } }, "invalidation": { "type": "string" }, "target": { "type": "string" }, "stop": { "type": "string" } } },
          "disclaimer": { "type": "string" }
        }
      },
      "SecurityData": {
        "type": "object",
        "properties": {
          "token": { "type": "string" },
          "available": { "type": "boolean" },
          "securityScore": { "type": ["integer", "null"], "description": "0-100, higher = safer" },
          "riskLevel": { "type": ["string", "null"], "enum": ["LOW", "MEDIUM", "HIGH", null] },
          "holderConcentration": { "type": ["object", "null"], "properties": { "status": { "type": "string" }, "detail": { "type": "string" } } },
          "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "detail": { "type": "string" } } } },
          "summary": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "CopilotData": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "analysis": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string" },
          "confidence": { "type": "string" },
          "watchItems": { "type": "array", "items": { "type": "string" } },
          "disclaimer": { "type": "string" }
        }
      },
      "OracleEnvelope": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OracleData" } } }] },
      "SecurityEnvelope": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SecurityData" } } }] },
      "CopilotEnvelope": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CopilotData" } } }] }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing": { "value": { "ok": false, "requestId": "req_…", "error": { "code": "missing_api_key", "message": "Provide an API key." }, "latencyMs": 0 } } } } } },
      "Forbidden": { "description": "API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "scope": { "value": { "ok": false, "requestId": "req_…", "error": { "code": "scope_forbidden", "message": "This API key does not have the 'oracle' scope." }, "latencyMs": 0 } } } } } },
      "RateLimited": { "description": "Rate limit or quota exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }
    }
  }
}