openapi: 3.0.3
info:
  title: FusionIntel Agentic Finance Hub
  description: |
    A股 / 港股 / 美股板块 / 大宗商品 的恐贪指数（抄底逃顶指数）+ 量价 + 板块衍生数据。
    专为 AI Agent 打造，原生支持 ChatGPT GPT Actions、Claude MCP、OpenClaw / WorkBuddy Skills。

    Fear & Greed score (0–100) interpretation:
    - 0–20: 极度恐惧 (Extreme Fear) — extreme fear, not a return forecast
    - >20–40: 恐惧 (Fear) — fear, not a bottom signal
    - >40–60: 中性 (Neutral) — monitor
    - >60–80: 贪婪 (Greed) — greed, not a top signal
    - >80–100: 极度贪婪 (Extreme Greed) — extreme greed, not a return forecast

    Auth: `X-API-Key` header. Get a free key at https://www.fusionintel.net/register
  version: "2.0.0"
  contact:
    name: FusionIntel Labs
    email: support@fusionintel.net
    url: https://www.fusionintel.net
  license:
    name: MIT

servers:
  - url: https://api.fusionintel.net
    description: Production

security:
  - ApiKeyAuth: []

tags:
  - name: Public
    description: 公开端点（无需 API Key），适合引流试用
  - name: A-Share Stock
    description: A 股个股量价
  - name: Fear & Greed
    description: 恐贪指数统一入口（9类）；Pro基础品种（含美股三大指数宏观恐贪）最近1年，Pro+增加商品及ETF恐贪最近3年，Max增加美股板块及A股个股恐贪全历史
  - name: Sector Aggregates
    description: 板块涨跌、情绪分布、热门板块

paths:
  # ─────────────────────────────────────────────────────────────
  # Public (no auth)
  # ─────────────────────────────────────────────────────────────
  /v1/public/feargreed/latest:
    get:
      operationId: getPublicMacroFeargreed
      tags: [Public]
      summary: 最新 A 股宏观恐贪快照（公开，无需 API Key）
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicSnapshot"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  # ─────────────────────────────────────────────────────────────
  # A-share stock OHLC
  # ─────────────────────────────────────────────────────────────
  /v1/stock/{code}:
    get:
      operationId: getStockPrice
      tags: [A-Share Stock]
      summary: 获取 A 股个股 OHLC + 涨停跌停
      parameters:
        - in: path
          name: code
          required: true
          description: A 股代码 (e.g. 000001.SZ, 600519.SH)
          schema:
            type: string
        - in: query
          name: period
          required: false
          description: 时间窗口 (free 套餐固定 30d)
          schema:
            type: string
            enum: [latest, 7d, 30d, 180d, 1y, 3y, all]
            default: 30d
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TablePayload"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/PlanRestricted"
        "429":
          $ref: "#/components/responses/RateLimit"

  # ─────────────────────────────────────────────────────────────
  # Fear & Greed (unified)
  # ─────────────────────────────────────────────────────────────
  /v1/feargreed/{category}/list:
    get:
      operationId: listFeargreedTargets
      tags: [Fear & Greed]
      summary: 列出指定恐贪类别下的全部标的
      parameters:
        - $ref: "#/components/parameters/Category"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InstrumentInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/PlanRestricted"

  /v1/feargreed/{category}/{code}:
    get:
      operationId: getFeargreed
      tags: [Fear & Greed]
      summary: 获取指定标的的恐贪指数时间序列
      parameters:
        - $ref: "#/components/parameters/Category"
        - in: path
          name: code
          required: true
          description: 标的代码 — 宏观 shi_feargreedindex/hsi_feargreedindex；A股板块 sector0001；港股板块 HK.LIST1180/EM.HK.039cddf0ea；美股板块 usi_041a9194a617；个股 000001.SZ；商品 AU/SC。先调用list取得真实代码。
          schema:
            type: string
        - in: query
          name: period
          required: false
          description: 免费仅A股宏观latest/7d/30d；Pro基础品种最长1y；Pro+增加商品及ETF恐贪最长3y；Max包含全部品种及all历史。
          schema:
            type: string
            enum: [latest, 7d, 30d, 180d, 1y, 3y, all]
            default: 30d
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TablePayload"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/PlanRestricted"
        "429":
          $ref: "#/components/responses/RateLimit"

  # ─────────────────────────────────────────────────────────────
  # Sector aggregates
  # ─────────────────────────────────────────────────────────────
  /v1/sectors/overview:
    get:
      operationId: getSectorsOverview
      tags: [Sector Aggregates]
      summary: 板块涨跌概览（上涨/下跌/平盘数）
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SectorsOverview"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/PlanRestricted"

  /v1/sectors/distribution:
    get:
      operationId: getSectorsDistribution
      tags: [Sector Aggregates]
      summary: 板块在 5 档情绪区间的分布
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SectorsDistribution"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/PlanRestricted"

  /v1/sectors/hot:
    get:
      operationId: getSectorsHot
      tags: [Sector Aggregates]
      summary: 情绪变化最大的热门板块
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/PlanRestricted"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Pass your sk_xxx key in the `X-API-Key` header.
        Get a free key at https://www.fusionintel.net/register

  parameters:
    Category:
      in: path
      name: category
      required: true
      description: 恐贪指数类别
      schema:
        type: string
        enum:
          - a_stock_macro
          - a_stock_sectors
          - a_stock_individual
          - us_stock_macro
          - hk_stock_macro
          - hk_stock_sectors
          - us_stock_sectors
          - a_stock_etf
          - commodity

  schemas:
    PublicSnapshot:
      type: object
      description: 公开宏观恐贪快照
      required: [category, code, latest_date, sh_index, feargreed_index, sentiment_label]
      properties:
        category:
          type: string
          example: a_stock_macro
        code:
          type: string
          example: shi_feargreedindex
        latest_date:
          type: string
          format: date
          example: "2026-05-12"
        sh_index:
          type: number
          example: 3245.68
        feargreed_index:
          type: number
          example: 42.5
        sentiment_label:
          type: string
          example: 中性
        source:
          type: string
        fetched_at:
          type: string
          format: date-time
        stale_seconds:
          type: integer
        is_stale:
          type: boolean

    TablePayload:
      type: object
      description: 表格化响应（量价 / 恐贪时间序列）
      required: [metadata, data]
      properties:
        metadata:
          type: object
          properties:
            symbol:
              type: string
            name:
              type: string
            category:
              type: string
            code:
              type: string
            period:
              type: string
            latest_date:
              type: string
            columns:
              type: array
              items:
                type: string
        data:
          type: array
          description: 行数组，每行各列含义见 metadata.columns
          items:
            type: array
            items: {}

    InstrumentInfo:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        category:
          type: string

    SectorsOverview:
      type: object
      properties:
        up_count:
          type: integer
        down_count:
          type: integer
        flat_count:
          type: integer
        total:
          type: integer

    SectorsDistribution:
      type: object
      properties:
        buckets:
          type: array
          items:
            type: object
            properties:
              range:
                type: string
              min:
                type: number
              max:
                type: number
              count:
                type: integer
              percent:
                type: number

    ErrorResponse:
      type: object
      required: [detail]
      properties:
        detail:
          type: string
          example: invalid api key

  responses:
    Unauthorized:
      description: 未授权 — API Key 缺失或无效
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    PlanRestricted:
      description: 套餐不足 — 升级链接 https://www.fusionintel.net/pricing
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimit:
      description: 超出每日调用限额（free 100/d, pro 1000/d, pro+ 3000/d）
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ServiceUnavailable:
      description: 服务暂不可用
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"