openapi: 3.1.0
info:
  title: cs2.sh API 文档
  version: 1.0.0
  description: |-
    Counter-Strike 2 饰品价格 REST API。所有 `/v1` 请求都需要：

    - `Authorization: Bearer <api_key>`：仪表盘中的 API 密钥。
    - `Accept-Encoding: gzip`：成功的 2xx 响应会经过 gzip 压缩。即使在 `/v1` 路径上，错误响应也不压缩。

    **套餐限制。** Demo 和 Developer 套餐可调用 `GET/POST /v1/prices/latest`、`GET /v1/market/buff/latest`、`GET /v1/market/steam/latest` 和 `GET /v1/schema`；其他端点会返回 `403 forbidden`。Scale 和 Enterprise 套餐拥有完整访问权限。

    **请求体限制。** POST 端点每个请求最多接受 100 个饰品（最大请求体 1 MiB）。未知 JSON 字段会被拒绝。值会会先去除首尾空白并去重，然后计入上限。

    **饰品。** 饰品通过 Steam `market_hash_name` 标识（例如 `USP-S | Printstream (Factory New)`）。

    **变体。** 通用价格、历史、归档、流动性和 BUFF 市场端点可为 Doppler / Gamma Doppler 相位或 Case Hardened 分层返回 `variants` 对象，见 `Variant`。专用 Steam 订单簿和原生 Steam 市场历史端点不支持变体，也不返回 `variants` 对象。

    **货币。** 所有价格均为 USD。
servers:
  - url: https://api.cs2.sh
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: Health
    description: 服务健康监控
  - name: Prices
    description: 当前和历史价格数据
  - name: Liquidity
    description: 流动性排名端点
  - name: BUFF Market
    description: BUFF 市场磨损/渐变区间端点
  - name: Steam Market
    description: 专用 Steam 社区市场订单簿和原生成交历史端点
  - name: Archive
    description: 具有多年覆盖范围的历史归档数据
  - name: Schema
    description: 完整饰品目录元数据
paths:
  /v1/prices/latest:
    get:
      operationId: getLatestPrices
      summary: 获取所有最新价格
      description: |
        返回所有受支持市场中所有饰品的当前价格。包含变体价格。

        **来源和可用字段：**
        - `buff`、`youpin`、`steam`：ask、ask_volume、bid、bid_volume
        - `c5game`：ask、ask_volume、bid
        - `csfloat`：ask、ask_volume、bid
        - `skinport`：ask、ask_volume、max_ask、mean_ask、median_ask

        带有特殊图案的饰品（Doppler 相位、Case Hardened 分层）会包含 `variants` 对象。变体的 `youpin` 对象在每个 Doppler 与 Gamma Doppler 相位上提供 ask、bid 与 bid_volume，大多数饰品还提供 ask_volume。
      tags:
        - Prices
      responses:
        '200':
          description: 所有饰品的当前价格
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestPricesGetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
    post:
      operationId: getLatestPricesFiltered
      summary: 获取指定饰品的最新价格
      description: 返回最多 100 个指定饰品的当前价格。
      tags:
        - Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  description: '`market_hash_name` 值列表（最多 100 个）'
                  example:
                    - USP-S | Printstream (Factory New)
                    - ★ Karambit | Doppler (Factory New)
      responses:
        '200':
          description: 请求饰品的当前价格
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestPricesPostResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/prices/history:
    post:
      operationId: getPriceHistory
      summary: 获取历史 OHLC 价格
      description: |
        返回持续更新的 OHLC（Open/High/Low/Close）价格历史。

        **覆盖范围：** 数据从 2025 年 12 月 24 日开始。

        **推荐用途：** 短期价格历史。

        **间隔和最大范围：**
        - `5m`：14 天
        - `30m`：90 天
        - `1h`：365 天
        - `1d`：不限
      tags:
        - Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
                - start
              properties:
                items:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  description: '`market_hash_name` 值列表（最多 100 个）'
                  example:
                    - USP-S | Printstream (Factory New)
                start:
                  type: string
                  description: 开始日期（YYYY-MM-DD 或 RFC3339）
                  example: '2026-07-20'
                end:
                  type: string
                  description: 结束日期（YYYY-MM-DD 或 RFC3339）。默认：现在
                  example: '2026-07-23'
                sources:
                  type: array
                  items:
                    type: string
                    enum:
                      - buff
                      - youpin
                      - csfloat
                      - skinport
                      - steam
                      - c5game
                  description: 过滤到指定来源。默认：全部来源
                  example:
                    - buff
                    - csfloat
                interval:
                  type: string
                  enum:
                    - 5m
                    - 30m
                    - 1h
                    - 1d
                  default: 5m
                  description: 聚合间隔
                  example: 1h
      responses:
        '200':
          description: 历史 OHLC 数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/liquidity/items:
    get:
      operationId: getItemLiquidity
      summary: 获取饰品流动性分档
      description: |
        返回所有饰品最新的每日流动性分档和预计售出时间。
      tags:
        - Liquidity
      responses:
        '200':
          description: 所有饰品的流动性
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemLiquidityGetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/archive/history:
    post:
      operationId: getArchiveHistory
      summary: 获取历史归档价格
      description: |
        从长期归档返回每个平台的历史价格数据。

        **响应字段：** 每个来源包含 ask、bid、ask_volume、bid_volume。`aggregate` 来源还包含 `hourly_volume` 和 `total_supply`。

        **间隔：**
        - `1h`：小时分桶
        - `1d`：日分桶（默认）

        **来源：** aggregate（全部合并）、buff、youpin、c5game

        **覆盖范围：** 自 2023 年起的数据。

        **推荐用途：** 长期价格历史、总供应量和成交量。

        **更新频率：** 归档端点每天约更新 1-2 次。

        **每个请求最多饰品数：** 100
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveHistoryRequest'
      responses:
        '200':
          description: 归档历史数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveHistoryResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/archive/csfloat:
    post:
      operationId: getArchiveCSFloat
      summary: 获取 CSFloat 历史成交
      description: |
        按日返回来自 CSFloat 的历史成交数据。

        **响应字段：**
        - `volume`：当天成交饰品数量
        - `price`：当天所有成交的算术平均价

        **覆盖范围：** 自 2022 年起的数据。

        **更新频率：** 归档端点每天约更新 1-2 次。

        **每个请求最多饰品数：** 100
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveCSFloatRequest'
      responses:
        '200':
          description: CSFloat 归档数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveCSFloatResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/archive/steam:
    post:
      operationId: getArchiveSteam
      summary: 获取原生 Steam 归档分桶
      description: |
        返回原生 Steam 社区市场成交历史分桶。`price` 是 Steam 对该分桶报告的成交中位价，`volume` 是 Steam 报告的购买次数。

        分桶是 Steam 原生的成交历史分桶，以 USD 计。间隔为 `1h` 和 `1d`，范围均不限。

        不支持变体。POST 路由最多接受 100 个饰品。仅 Scale 和 Enterprise 套餐可访问。
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveSteamRequest'
      responses:
        '200':
          description: 按饰品分组的原生 Steam 归档分桶
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveSteamResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/archive/youpin:
    post:
      operationId: getArchiveYoupin
      summary: 获取 Youpin 成交历史
      description: |
        返回 1h / 4h / 12h 间隔的 Youpin 成交价格。Youpin 对每个抽样分桶（1h / 4h / 12h）只发布一笔成交，这意味着若某件饰品在该时段内有多笔成交，只会使用最近的一笔。价格为 USD，按每笔成交所在日期各自的历史汇率由 CNY 换算。

        **按间隔的序列：** 每件饰品在 `intervals` 下按宽度各携带一条独立序列，键为 `1h`、`4h` 和 `12h`。只有该宽度在请求窗口内被观测过时键才存在：`count: 0` 加空 `data` 表示观测过且无成交，键不存在表示未被观测。同一笔成交可以出现在多个宽度中，序列绝不能求和。

        **响应字段：**
        - `bucket`：抽样分桶的起点
        - `time`：分桶内实际成交时间
        - `price`：成交价（USD）
        - `count`：该条序列中的点数量，不是成交量

        **覆盖范围：** `12h` 数据自 2025 年 11 月 12 日起；`4h` 自 2026 年 6 月 27 日起；`1h` 自 2026 年 7 月 20 日起。采集 `/v1/liquidity/items` 上 `liquid` 及以上档位的饰品，约 16,000 件，外加 Doppler、Gamma Doppler 与 Case Hardened 变体。

        **更新频率：** 每天约更新 1-2 次。

        **每次请求最大饰品数：** 100
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveYoupinRequest'
      responses:
        '200':
          description: Youpin 成交历史
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveYoupinResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/market/buff/latest:
    get:
      operationId: getBuffMarketLatest
      summary: 获取每件饰品的 BUFF 磨损与渐变区间
      description: |
        返回每件饰品的 BUFF 磨损与渐变区间。每件饰品有一个或多个由 `bucket_type` 标识的区间：`base`、`float`、`fade` 或 `float_fade`。具备 Doppler 相位或 Case Hardened 分层的饰品可包含 `variants` 对象。

        BUFF 每 10 分钟刷新一次磨损与渐变区间。

        所有价格均为 USD。

        Demo、Developer、Scale 和 Enterprise 套餐均可访问。
      tags:
        - BUFF Market
      responses:
        '200':
          description: 所有饰品的 BUFF 市场磨损/渐变区间
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BUFFMarketFloatLatestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/market/buff/history:
    post:
      operationId: getBuffMarketHistory
      summary: 获取 BUFF 磨损与渐变区间的 OHLC 历史
      description: |
        返回 BUFF 磨损与渐变区间的 OHLC 历史。

        **覆盖范围：** 数据自 2026 年 5 月 19 日起。

        **间隔与最大范围：**
        - `30m`：90 天
        - `1h`：365 天
        - `1d`：不限

        必填字段：`items`、`start`。`end` 默认现在。`interval` 默认 `30m`。
      tags:
        - BUFF Market
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BUFFMarketFloatHistoryRequest'
      responses:
        '200':
          description: BUFF 市场磨损/渐变 OHLC 历史
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BUFFMarketFloatHistoryResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/market/steam/latest:
    get:
      operationId: getSteamLatest
      summary: 获取最新 Steam 全深度订单簿
      description: |
        返回所有被追踪常规饰品的最新完整 Steam 买/卖订单簿。

        订单簿深度采用列式结构。`depth.asks.prices` 按升序排列，`depth.bids.prices` 按降序排列，`volumes` 中的每个值都对应相同数组索引处的价格。所有价格均为 USD。

        Demo、Developer、Scale 和 Enterprise 套餐均可访问。
      tags:
        - Steam Market
      responses:
        '200':
          description: 已跟踪常规饰品的最新 Steam 全深度订单簿
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SteamOrderbookLatestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/market/steam/history:
    post:
      operationId: getSteamHistory
      summary: 获取 Steam 订单簿分桶快照
      description: |
        返回随时间变化的完整 Steam 订单簿快照。每个分桶包含该区间内采集到的最后一次 Steam 观测，深度结构与 `GET /v1/market/steam/latest` 相同。

        这是某一时刻的深度数据，而非 OHLC；价格不会被聚合。分桶仅为 USD。间隔为 `1h`（90 天）和 `1d`（不限）。

        不支持变体。POST 路由最多接受 100 个饰品。仅 Scale 和 Enterprise 套餐可访问。
      tags:
        - Steam Market
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SteamOrderbookHistoryRequest'
      responses:
        '200':
          description: 按饰品和分桶分组的 Steam 订单簿快照
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SteamOrderbookHistoryResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /v1/schema:
    get:
      operationId: getSchema
      summary: 获取饰品目录
      description: |
        返回一份包含所有 Counter-Strike 2 饰品的完整 schema。它会在游戏更新时自动更新，包含约 47,500 件饰品和约 110 个收藏品，按 `market_hash_name` 键控，并提供稀有度、外观与磨损区间、市场 id 和饰品图片。支持变体。适用时，饰品会列出所属收藏品和掉落容器。

        完整负载较大，因此需要 `Accept-Encoding: gzip`。

        所有套餐均可访问。
      tags:
        - Schema
      responses:
        '200':
          description: 完整饰品目录
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /health:
    get:
      operationId: getHealth
      summary: 服务健康状态
      description: |
        返回当前来源、变体、端点、schema 和汇总健康状态。不需要认证。

        只要健康数据已就绪，即使 `status` 为 `degraded` 或 `down` 也会返回 HTTP `200`。HTTP `503` 表示健康数据尚未就绪。
      tags:
        - Health
      security: []
      responses:
        '200':
          description: 服务健康状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
                example:
                  status: up
                  last_refreshed_at: '2026-07-26T18:54:15.442085768Z'
                  schema_ready: true
                  sources:
                    buff:
                      updated_at: '2026-07-26T18:50:49Z'
                      collected_at: '2026-07-26T18:53:10.67Z'
                      status: up
                    c5game:
                      updated_at: '2026-07-26T18:48:08.979Z'
                      collected_at: '2026-07-26T18:51:38.285Z'
                      status: up
                    csfloat:
                      updated_at: '2026-07-26T18:53:05.094Z'
                      collected_at: '2026-07-26T18:53:05.134Z'
                      status: up
                    skinport:
                      updated_at: '2026-07-26T18:53:09.397Z'
                      collected_at: '2026-07-26T18:53:15.672Z'
                      status: up
                    steam:
                      updated_at: '2026-07-26T18:52:08.812Z'
                      collected_at: '2026-07-26T18:52:54.624Z'
                      status: up
                    youpin:
                      updated_at: '2026-07-26T18:53:20.241Z'
                      collected_at: '2026-07-26T18:53:26.895Z'
                      status: up
                  variants:
                    buff_variant:
                      updated_at: '2026-07-26T18:50:48Z'
                      collected_at: '2026-07-26T18:53:10.67Z'
                      status: up
                    c5game_variant:
                      updated_at: '2026-07-26T18:47:01.827Z'
                      collected_at: '2026-07-26T18:51:38.285Z'
                      status: up
                    csfloat_variant:
                      updated_at: '2026-07-26T18:53:16.358Z'
                      collected_at: '2026-07-26T18:53:30.141Z'
                      status: up
                    skinport_variant:
                      updated_at: '2026-07-26T18:53:09.397Z'
                      collected_at: '2026-07-26T18:53:15.672Z'
                      status: up
                    youpin_variant:
                      updated_at: '2026-07-26T18:53:26.905Z'
                      collected_at: '2026-07-26T18:53:29.758Z'
                      status: up
                  endpoints:
                    archive/csfloat:
                      updated_at: '2026-07-26T00:00:00Z'
                      collected_at: '2026-07-26T18:53:56.265Z'
                      status: up
                    archive/history:
                      updated_at: '2026-07-26T03:59:39Z'
                      collected_at: '2026-07-26T04:01:52.044Z'
                      status: up
                    archive/steam:
                      updated_at: '2026-07-26T17:00:00Z'
                      collected_at: '2026-07-26T17:00:00Z'
                      status: up
                    liquidity:
                      updated_at: '2026-07-26T18:36:42Z'
                      collected_at: '2026-07-26T18:40:06.941Z'
                      status: up
                    liquidity/items:
                      updated_at: '2026-07-26T00:00:00Z'
                      collected_at: '2026-07-26T00:00:29.508Z'
                      status: up
                    market/buff/history:
                      updated_at: '2026-07-26T18:50:54.164Z'
                      collected_at: '2026-07-26T18:50:54.164Z'
                      status: up
                    market/buff/latest:
                      updated_at: '2026-07-26T18:50:54.164Z'
                      collected_at: '2026-07-26T18:50:54.164Z'
                      status: up
                    market/steam/history:
                      updated_at: '2026-07-26T18:00:00Z'
                      collected_at: '2026-07-26T18:00:00Z'
                      status: up
                    market/steam/latest:
                      updated_at: '2026-07-26T18:52:53.402Z'
                      collected_at: '2026-07-26T18:52:56.46Z'
                      status: up
                    prices/history:
                      updated_at: '2026-07-26T18:50:00Z'
                      collected_at: '2026-07-26T18:50:00Z'
                      status: up
                    prices/latest:
                      updated_at: '2026-07-26T18:53:16.358Z'
                      collected_at: '2026-07-26T18:53:30.141Z'
                      status: up
                    schema:
                      updated_at: '2026-07-20T22:44:41Z'
                      collected_at: '2026-07-26T05:30:26.938145778Z'
                      status: up
                  stats:
                    total_events: 27426561632
                    market_hash_names: 43906
                    variant_items: 1372
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        为你的 cs2.sh 账户签发的 API 密钥。演示密钥超过签发时标明的到期时间后，
        会返回带有 `demo key expired` 的 `401 unauthorized`；有效期可能因签发渠道而异。

        Demo 和 Developer 套餐仅限访问 `GET/POST /v1/prices/latest`、`GET /v1/market/buff/latest`、`GET /v1/market/steam/latest` 和 `GET /v1/schema`。其他端点会返回 `403 forbidden`。
  schemas:
    HealthEntry:
      type: object
      description: 单个来源、变体采集器或端点数据集的新鲜度和状态。
      required:
        - updated_at
        - collected_at
        - status
      properties:
        updated_at:
          type: string
          format: date-time
          description: 此条目所代表数据的最新来源时间。
        collected_at:
          type: string
          format: date-time
          description: cs2.sh 最近采集或生成此数据集的时间。
        status:
          type: string
          enum:
            - up
            - degraded
            - down
          description: 根据数据集预期刷新频率计算的健康状态。
    HealthStats:
      type: object
      description: 上次健康状态刷新时的数据库汇总计数。
      required:
        - total_events
        - market_hash_names
        - variant_items
      properties:
        total_events:
          type: integer
          description: 已存储的市场数据事件总数。
        market_hash_names:
          type: integer
          description: 当前市场数据中唯一饰品名称的数量。
        variant_items:
          type: integer
          description: 当前市场数据中唯一变体饰品名称的数量。
    HealthResponse:
      type: object
      description: cs2.sh 数据来源和公共数据集的当前健康状态。
      required:
        - status
        - last_refreshed_at
        - schema_ready
        - sources
        - variants
        - endpoints
        - stats
      properties:
        status:
          type: string
          enum:
            - up
            - degraded
            - down
          description: API 数据的整体健康状态。
        last_refreshed_at:
          type: string
          format: date-time
          description: 此健康快照的生成时间。
        schema_ready:
          type: boolean
          description: 饰品 schema 是否可用。
        sources:
          type: object
          description: 按来源键控的市场健康状态。
          additionalProperties:
            $ref: '#/components/schemas/HealthEntry'
        variants:
          type: object
          description: 按来源采集器键控的变体价格健康状态。
          additionalProperties:
            $ref: '#/components/schemas/HealthEntry'
        endpoints:
          type: object
          description: 按端点名称键控的数据集健康状态。
          additionalProperties:
            $ref: '#/components/schemas/HealthEntry'
        stats:
          $ref: '#/components/schemas/HealthStats'
    SkinportPriceWindow:
      type: object
      required: [price, max_price, mean_price, median_price, volume]
      description: Skinport 提供的滚动价格窗口。当 Skinport 最近没有该饰品成交时，对象为 `null`。
      properties:
        price:
          type: number
          description: 窗口内最近成交价（USD）
        max_price:
          type: number
          description: 窗口内最高成交价（USD）
        mean_price:
          type: number
          description: 窗口内平均成交价（USD）
        median_price:
          type: number
          description: 窗口内成交价中位数（USD）
        volume:
          type: integer
          description: 窗口内成交次数
    BUFFSourceData:
      type: object
      required: [updated_at, collected_at, ask, ask_volume, bid, bid_volume]
      description: 来自 BUFF 的价格数据。
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: BUFF 上次更新此价格的时间
        collected_at:
          type: [string, "null"]
          format: date-time
          description: cs2.sh 拉取此数据的时间
        ask:
          type: [number, "null"]
          description: 最低 ask 价格（USD）
        ask_volume:
          type: [integer, "null"]
          description: 在售饰品数量
        bid:
          type: [number, "null"]
          description: 最高求购单价格（USD）
        bid_volume:
          type: [integer, "null"]
          description: 活跃求购单数量
    YoupinSourceData:
      type: object
      required: [updated_at, collected_at, ask, ask_volume, bid, bid_volume]
      description: 来自 Youpin898 的价格数据。
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: Youpin 上次更新此价格的时间
        collected_at:
          type: [string, "null"]
          format: date-time
          description: cs2.sh 拉取此数据的时间
        ask:
          type: [number, "null"]
          description: 最低 ask 价格（USD）
        ask_volume:
          type: [integer, "null"]
          description: 在售饰品数量
        bid:
          type: [number, "null"]
          description: 最高求购单价格（USD）
        bid_volume:
          type: [integer, "null"]
          description: 活跃求购单数量
    CsfloatSourceData:
      type: object
      required: [updated_at, collected_at, ask, ask_volume, bid]
      description: 来自 CSFloat 的当前挂单与求购单价格。
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: CSFloat 上次更新此价格的时间
        collected_at:
          type: [string, "null"]
          format: date-time
          description: cs2.sh 拉取此数据的时间
        ask:
          type: [number, "null"]
          description: 最低 ask 价格（USD）
        ask_volume:
          type: [integer, "null"]
          description: 在售饰品数量
        bid:
          type: [number, "null"]
          description: 最高求购单价格（USD）
    SkinportSourceData:
      type: object
      required: [updated_at, collected_at, ask, ask_volume, max_ask, mean_ask, median_ask, 24h_history, 7d_history, 30d_history, 90d_history]
      description: 来自 Skinport 的价格数据，包括 Skinport 提供的滚动历史窗口。
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: Skinport 上次更新此价格的时间
        collected_at:
          type: [string, "null"]
          format: date-time
          description: cs2.sh 拉取此数据的时间
        ask:
          type: [number, "null"]
          description: 最低 ask 价格（USD）
        ask_volume:
          type: [integer, "null"]
          description: 在售饰品数量
        max_ask:
          type: [number, "null"]
          description: 最高挂单价（USD）
        mean_ask:
          type: [number, "null"]
          description: 平均挂单价（USD）
        median_ask:
          type: [number, "null"]
          description: 挂单价中位数（USD）
        24h_history:
          oneOf:
            - $ref: '#/components/schemas/SkinportPriceWindow'
            - type: "null"
        7d_history:
          oneOf:
            - $ref: '#/components/schemas/SkinportPriceWindow'
            - type: "null"
        30d_history:
          oneOf:
            - $ref: '#/components/schemas/SkinportPriceWindow'
            - type: "null"
        90d_history:
          oneOf:
            - $ref: '#/components/schemas/SkinportPriceWindow'
            - type: "null"
    SteamSourceData:
      type: object
      required: [updated_at, collected_at, ask, ask_volume, bid, bid_volume]
      description: 来自 Steam 社区市场的价格数据。
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: 上游价格上次更新的时间
        collected_at:
          type: [string, "null"]
          format: date-time
          description: cs2.sh 拉取此数据的时间
        ask:
          type: [number, "null"]
          description: 最低 ask 价格（USD）
        ask_volume:
          type: [integer, "null"]
          description: 在售饰品数量
        bid:
          type: [number, "null"]
          description: 最高求购单价格（USD）
        bid_volume:
          type: [integer, "null"]
          description: 活跃求购单数量
    C5GameSourceData:
      type: object
      required: [updated_at, collected_at, ask, ask_volume, bid]
      description: 来自 C5Game 的价格数据。Ask 和 bid 来自独立采集流程，因此同一饰品的时间戳可能不同。
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: C5Game 上次更新此价格的时间
        collected_at:
          type: [string, "null"]
          format: date-time
          description: cs2.sh 拉取此数据的时间
        ask:
          type: [number, "null"]
          description: 最低 ask 价格（USD）
        ask_volume:
          type: [integer, "null"]
          description: 在售饰品数量
        bid:
          type: [number, "null"]
          description: 最高求购单价格（USD）
    Variant:
      type: object
      required: [market_hash_name, name, display_name, version]
      description: 饰品的一个变体（Doppler / Gamma Doppler 相位或 Case Hardened 分层）。`youpin` 在每个 Doppler 与 Gamma Doppler 相位上提供 `ask`、`bid` 与 `bid_volume`，大多数饰品还提供 `ask_volume`。
      properties:
        market_hash_name:
          type: string
          description: 基础饰品 `market_hash_name`。完整变体名称见：`name`。
        name:
          type: string
          description: 变体的完整 `market_hash_name`，例如 `★ Karambit | Doppler (Factory New) | Phase 1`。
        display_name:
          type: string
          description: 人类可读的变体标签（例如 `Phase 1`、`Ruby`、`Tier 1`、`Blue Gem`）。
        version:
          type: string
          description: 稳定变体代码。客户端代码应基于此切换。
          enum:
            - p1
            - p2
            - p3
            - p4
            - ruby
            - sapphire
            - blackpearl
            - emerald
            - t1
            - t2
            - t3
            - t4
            - singleblue
        buff:
          $ref: '#/components/schemas/BUFFSourceData'
        youpin:
          $ref: '#/components/schemas/YoupinSourceData'
        csfloat:
          $ref: '#/components/schemas/CsfloatSourceData'
        skinport:
          $ref: '#/components/schemas/SkinportSourceData'
        c5game:
          $ref: '#/components/schemas/C5GameSourceData'
        steam:
          $ref: '#/components/schemas/SteamSourceData'
    Item:
      type: object
      required: [market_hash_name, buff, youpin, csfloat, skinport, c5game, steam]
      description: 一个饰品在所有来源上的价格数据。
      properties:
        market_hash_name:
          type: string
          description: Steam 市场哈希名称（规范饰品标识符）。
        buff:
          $ref: '#/components/schemas/BUFFSourceData'
        youpin:
          $ref: '#/components/schemas/YoupinSourceData'
        csfloat:
          $ref: '#/components/schemas/CsfloatSourceData'
        skinport:
          $ref: '#/components/schemas/SkinportSourceData'
        c5game:
          $ref: '#/components/schemas/C5GameSourceData'
        steam:
          $ref: '#/components/schemas/SteamSourceData'
        variants:
          type: object
          description: 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体价格数据。按显示名称作为键。
          additionalProperties:
            $ref: '#/components/schemas/Variant'
    LatestPricesGetResponse:
      type: object
      required: [response_time, currency, items]
      description: 全量饰品快照。由 `GET /v1/prices/latest` 返回，带有共享响应元数据。
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间
        currency:
          type: string
          description: 货币代码（始终为 `USD`）
        items:
          type: object
          description: '`market_hash_name` 到饰品价格数据的映射。'
          additionalProperties:
            $ref: '#/components/schemas/Item'
      example:
        response_time: '2026-07-26T18:54:04.041256216Z'
        currency: USD
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            buff:
              updated_at: '2026-07-26T18:50:53Z'
              collected_at: '2026-07-26T18:53:10.67Z'
              ask: 109.72
              ask_volume: 463
              bid: 106.17
              bid_volume: 41
            youpin:
              updated_at: '2026-07-26T18:52:35.85Z'
              collected_at: '2026-07-26T18:52:41.584Z'
              ask: 108.24
              ask_volume: 507
              bid: 107.06
              bid_volume: 63
            csfloat:
              updated_at: '2026-07-26T18:53:05.094Z'
              collected_at: '2026-07-26T18:53:05.134Z'
              ask: 107.99
              ask_volume: 227
              bid: 105
            skinport:
              updated_at: '2026-07-26T18:53:09.397Z'
              collected_at: '2026-07-26T18:53:15.672Z'
              ask: 115.95
              ask_volume: 39
              max_ask: 575.78
              mean_ask: 181.61
              median_ask: 156.61
              24h_history:
                price: 113.78
                max_price: 116.48
                mean_price: 115.13
                median_price: 115.13
                volume: 2
              7d_history:
                price: 102.41
                max_price: 147.72
                mean_price: 118.31
                median_price: 113.79
                volume: 7
              30d_history:
                price: 102.41
                max_price: 147.72
                mean_price: 119.16
                median_price: 118.57
                volume: 44
              90d_history:
                price: 96.72
                max_price: 210.73
                mean_price: 123.13
                median_price: 119.33
                volume: 149
            steam:
              updated_at: '2026-07-26T18:52:21.42Z'
              collected_at: '2026-07-26T18:52:54.624Z'
              ask: 169.14
              ask_volume: 70
              bid: 155.05
              bid_volume: 2951
            c5game:
              updated_at: '2026-07-26T18:49:05.186Z'
              collected_at: '2026-07-26T18:49:07.9Z'
              ask: 113.56
              ask_volume: 141
              bid: 221.65
    LatestPricesPostResponse:
      type: object
      required: [response_time, currency, items]
      description: 按饰品过滤的快照。由 `POST /v1/prices/latest` 返回，包含逐饰品 `errors`。
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间
        currency:
          type: string
          description: 货币代码（始终为 `USD`）
        items:
          type: object
          description: '`market_hash_name` 到饰品价格数据的映射，过滤到请求的饰品。'
          additionalProperties:
            $ref: '#/components/schemas/Item'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 与成功结果一起返回的逐饰品失败（部分成功）。
      example:
        response_time: '2026-08-16T02:40:27.537385456Z'
        currency: USD
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            buff:
              updated_at: '2026-08-16T02:36:51Z'
              collected_at: '2026-08-16T02:39:08.389Z'
              ask: 98.72
              ask_volume: 509
              bid: 97.61
              bid_volume: 38
            youpin:
              updated_at: '2026-08-16T02:34:11.218Z'
              collected_at: '2026-08-16T02:34:19.719Z'
              ask: 101.61
              ask_volume: 540
              bid: 99.39
              bid_volume: 64
            csfloat:
              updated_at: '2026-08-16T02:39:06.114Z'
              collected_at: '2026-08-16T02:39:06.156Z'
              ask: 98.84
              ask_volume: 244
              bid: 97
            skinport:
              updated_at: '2026-08-16T02:39:10.489Z'
              collected_at: '2026-08-16T02:39:17.102Z'
              ask: 106.28
              ask_volume: 62
              max_ask: 586
              mean_ask: 165.9
              median_ask: 141.66
              24h_history:
                price: 106.08
                max_price: 106.08
                mean_price: 106.08
                median_price: 106.08
                volume: 1
              7d_history:
                price: 103.44
                max_price: 163.45
                mean_price: 112.27
                median_price: 106.42
                volume: 10
              30d_history:
                price: 103.44
                max_price: 190.96
                mean_price: 118.68
                median_price: 115.8
                volume: 34
              90d_history:
                price: 98.44
                max_price: 214.47
                mean_price: 120.23
                median_price: 118.11
                volume: 139
            steam:
              updated_at: '2026-08-16T02:38:15.395Z'
              collected_at: '2026-08-16T02:38:15.765Z'
              ask: 154.58
              ask_volume: 64
              bid: 148.73
              bid_volume: 2847
            c5game:
              updated_at: '2026-08-16T02:39:16.373Z'
              collected_at: '2026-08-16T02:39:17.181Z'
              ask: 103.25
              ask_volume: 231
              bid: 203.82
          ★ Karambit | Doppler (Factory New):
            market_hash_name: ★ Karambit | Doppler (Factory New)
            buff:
              updated_at: '2026-08-16T02:36:29Z'
              collected_at: '2026-08-16T02:39:08.389Z'
              ask: 1320.24
              ask_volume: 1592
              bid: 1265.35
              bid_volume: 73
            youpin:
              updated_at: '2026-08-16T02:39:15.117Z'
              collected_at: '2026-08-16T02:39:30.793Z'
              ask: 1275.36
              ask_volume: 1654
              bid: 1257.94
              bid_volume: 24
            csfloat:
              updated_at: '2026-08-16T02:39:06.114Z'
              collected_at: '2026-08-16T02:39:06.156Z'
              ask: 1262
              ask_volume: 958
              bid: null
            skinport:
              updated_at: null
              collected_at: null
              ask: null
              ask_volume: null
              max_ask: null
              mean_ask: null
              median_ask: null
              24h_history: null
              7d_history: null
              30d_history: null
              90d_history: null
            steam:
              updated_at: '2026-08-16T02:38:51.747Z'
              collected_at: '2026-08-16T02:38:52.055Z'
              ask: 1932.57
              ask_volume: 1
              bid: 1790.09
              bid_volume: 6564
            c5game:
              updated_at: '2026-08-16T02:39:00.4Z'
              collected_at: '2026-08-16T02:39:01.15Z'
              ask: 1304.49
              ask_volume: 315
              bid: 1253.49
            variants:
              Phase 2:
                market_hash_name: ★ Karambit | Doppler (Factory New)
                name: ★ Karambit | Doppler (Factory New) | Phase 2
                display_name: Phase 2
                version: p2
                buff:
                  updated_at: '2026-08-16T02:36:29Z'
                  collected_at: '2026-08-16T02:39:08.389Z'
                  ask: 1876.52
                  ask_volume: null
                  bid: 1802.35
                  bid_volume: null
                youpin:
                  updated_at: '2026-08-16T02:38:00.447Z'
                  collected_at: '2026-08-16T02:38:27.248Z'
                  ask: 1824.06
                  ask_volume: 445
                  bid: 1794.93
                  bid_volume: 39
                csfloat:
                  updated_at: '2026-08-16T02:33:30.519Z'
                  collected_at: '2026-08-16T02:33:30.541Z'
                  ask: 1851.86
                  ask_volume: null
                  bid: 1800
                c5game:
                  updated_at: '2026-08-16T02:35:44.486Z'
                  collected_at: '2026-08-16T02:36:52.69Z'
                  ask: 1868.55
                  ask_volume: 67
                  bid: 1794.93
              Ruby:
                market_hash_name: ★ Karambit | Doppler (Factory New)
                name: ★ Karambit | Doppler (Factory New) | Ruby
                display_name: Ruby
                version: ruby
                buff:
                  updated_at: '2026-08-16T02:36:29Z'
                  collected_at: '2026-08-16T02:39:08.389Z'
                  ask: 7713.76
                  ask_volume: null
                  bid: 7053.64
                  bid_volume: null
                youpin:
                  updated_at: '2026-08-16T02:38:00.447Z'
                  collected_at: '2026-08-16T02:38:27.248Z'
                  ask: 7680.03
                  ask_volume: 69
                  bid: 7250.93
                  bid_volume: 36
                csfloat:
                  updated_at: '2026-08-16T02:37:08.797Z'
                  collected_at: '2026-08-16T02:37:37.562Z'
                  ask: 7723
                  ask_volume: null
                  bid: 7220
                c5game:
                  updated_at: '2026-08-16T02:35:45.934Z'
                  collected_at: '2026-08-16T02:36:52.69Z'
                  ask: 8156.36
                  ask_volume: 12
                  bid: 6230.34
    BUFFOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, open_bid, high_bid, low_bid, close_bid, bid_volume, sample_count, open_time, close_time]
      description: BUFF 价格的 OHLC 分桶。
      properties:
        open_ask:
          type: [number, "null"]
          description: 分桶内第一个 ask 价格
        high_ask:
          type: [number, "null"]
          description: 分桶内最高 ask 价格
        low_ask:
          type: [number, "null"]
          description: 分桶内最低 ask 价格
        close_ask:
          type: [number, "null"]
          description: 分桶内最后一个 ask 价格
        ask_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 ask 成交量
        open_bid:
          type: [number, "null"]
          description: 分桶内第一个 bid 价格
        high_bid:
          type: [number, "null"]
          description: 分桶内最高 bid 价格
        low_bid:
          type: [number, "null"]
          description: 分桶内最低 bid 价格
        close_bid:
          type: [number, "null"]
          description: 分桶内最后一个 bid 价格
        bid_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 bid 成交量
        sample_count:
          type: integer
          description: 聚合到此分桶的底层 5 分钟观测数量
        open_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。
        close_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。
    YoupinOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, open_bid, high_bid, low_bid, close_bid, bid_volume, sample_count, open_time, close_time]
      description: Youpin 价格的 OHLC 分桶。
      properties:
        open_ask:
          type: [number, "null"]
          description: 分桶内第一个 ask 价格
        high_ask:
          type: [number, "null"]
          description: 分桶内最高 ask 价格
        low_ask:
          type: [number, "null"]
          description: 分桶内最低 ask 价格
        close_ask:
          type: [number, "null"]
          description: 分桶内最后一个 ask 价格
        ask_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 ask 成交量
        open_bid:
          type: [number, "null"]
          description: 分桶内第一个 bid 价格
        high_bid:
          type: [number, "null"]
          description: 分桶内最高 bid 价格
        low_bid:
          type: [number, "null"]
          description: 分桶内最低 bid 价格
        close_bid:
          type: [number, "null"]
          description: 分桶内最后一个 bid 价格
        bid_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 bid 成交量
        sample_count:
          type: integer
          description: 聚合到此分桶的底层 5 分钟观测数量
        open_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。
        close_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。
    CsfloatOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, open_bid, high_bid, low_bid, close_bid, sample_count, open_time, close_time]
      description: CSFloat ask 与 bid 价格的 OHLC 分桶。
      properties:
        open_ask:
          type: [number, "null"]
          description: 分桶内第一个 ask 价格
        high_ask:
          type: [number, "null"]
          description: 分桶内最高 ask 价格
        low_ask:
          type: [number, "null"]
          description: 分桶内最低 ask 价格
        close_ask:
          type: [number, "null"]
          description: 分桶内最后一个 ask 价格
        ask_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 ask 成交量
        open_bid:
          type: [number, "null"]
          description: 分桶内第一个 bid 价格
        high_bid:
          type: [number, "null"]
          description: 分桶内最高 bid 价格
        low_bid:
          type: [number, "null"]
          description: 分桶内最低 bid 价格
        close_bid:
          type: [number, "null"]
          description: 分桶内最后一个 bid 价格
        sample_count:
          type: integer
          description: 聚合到此分桶的底层 5 分钟观测数量
        open_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。
        close_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。
    SkinportOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, sample_count, open_time, close_time]
      description: Skinport ask 价格的 OHLC 分桶。
      properties:
        open_ask:
          type: [number, "null"]
          description: 分桶内第一个 ask 价格
        high_ask:
          type: [number, "null"]
          description: 分桶内最高 ask 价格
        low_ask:
          type: [number, "null"]
          description: 分桶内最低 ask 价格
        close_ask:
          type: [number, "null"]
          description: 分桶内最后一个 ask 价格
        ask_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 ask 成交量
        sample_count:
          type: integer
          description: 聚合到此分桶的底层 5 分钟观测数量
        open_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。
        close_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。
    SteamOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, open_bid, high_bid, low_bid, close_bid, bid_volume, sample_count, open_time, close_time]
      description: Steam Community Market ask 和 bid 价格的 OHLC 分桶。
      properties:
        open_ask:
          type: [number, "null"]
          description: 分桶内第一个 ask 价格
        high_ask:
          type: [number, "null"]
          description: 分桶内最高 ask 价格
        low_ask:
          type: [number, "null"]
          description: 分桶内最低 ask 价格
        close_ask:
          type: [number, "null"]
          description: 分桶内最后一个 ask 价格
        ask_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 ask 成交量
        open_bid:
          type: [number, "null"]
          description: 分桶内第一个 bid 价格
        high_bid:
          type: [number, "null"]
          description: 分桶内最高 bid 价格
        low_bid:
          type: [number, "null"]
          description: 分桶内最低 bid 价格
        close_bid:
          type: [number, "null"]
          description: 分桶内最后一个 bid 价格
        bid_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 bid 成交量
        sample_count:
          type: integer
          description: 聚合到此分桶的底层 5 分钟观测数量
        open_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。
        close_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。
    C5GameOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, open_bid, high_bid, low_bid, close_bid, sample_count, open_time, close_time]
      description: C5Game ask 和 bid 价格的 OHLC 分桶。
      properties:
        open_ask:
          type: [number, "null"]
          description: 分桶内第一个 ask 价格
        high_ask:
          type: [number, "null"]
          description: 分桶内最高 ask 价格
        low_ask:
          type: [number, "null"]
          description: 分桶内最低 ask 价格
        close_ask:
          type: [number, "null"]
          description: 分桶内最后一个 ask 价格
        ask_volume:
          type: [integer, "null"]
          description: 分桶内最后观测到的 ask 成交量
        open_bid:
          type: [number, "null"]
          description: 分桶内第一个 bid 价格
        high_bid:
          type: [number, "null"]
          description: 分桶内最高 bid 价格
        low_bid:
          type: [number, "null"]
          description: 分桶内最低 bid 价格
        close_bid:
          type: [number, "null"]
          description: 分桶内最后一个 bid 价格
        sample_count:
          type: integer
          description: 聚合到此分桶的底层 5 分钟观测数量
        open_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。
        close_time:
          type: [string, "null"]
          format: date-time
          description: 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。
    HistoryBucket:
      type: object
      required: [bucket]
      description: 单个 OHLC 时间分桶。`bucket` 是间隔边界（UTC 对齐、确定性）；每个按来源对象上的 `open_time`/`close_time` 是其中实际第一次/最后一次观测时间戳。
      properties:
        bucket:
          type: string
          format: date-time
          description: 时间分桶的开始时间。UTC 对齐到间隔边界（例如 `1h` 分桶的 `2026-01-08T19:00:00Z`）。确定性。
        buff:
          $ref: '#/components/schemas/BUFFOHLCSourceData'
        youpin:
          $ref: '#/components/schemas/YoupinOHLCSourceData'
        csfloat:
          $ref: '#/components/schemas/CsfloatOHLCSourceData'
        skinport:
          $ref: '#/components/schemas/SkinportOHLCSourceData'
        c5game:
          $ref: '#/components/schemas/C5GameOHLCSourceData'
        steam:
          $ref: '#/components/schemas/SteamOHLCSourceData'
    HistoryItem:
      type: object
      required: [market_hash_name, count, data]
      description: 单个饰品的 OHLC 时间序列。
      properties:
        market_hash_name:
          type: string
          description: Steam 市场哈希名称（规范饰品标识符）。
        count:
          type: integer
          description: 有数据的分桶数量
        data:
          type: array
          description: 按时间顺序排列的 OHLC 分桶。
          items:
            $ref: '#/components/schemas/HistoryBucket'
        variants:
          type: object
          description: 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 OHLC 时间序列。按显示名称作为键。
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, count, data]
            properties:
              market_hash_name:
                type: string
                description: 基础饰品的 `market_hash_name`。
              name:
                type: string
                description: 变体的完整 `market_hash_name`。
              display_name:
                type: string
                description: 人类可读的变体标签。
              version:
                type: string
                description: 稳定变体代码。
              count:
                type: integer
                description: 此变体有数据的分桶数量。
              data:
                type: array
                description: 按时间顺序排列的 OHLC 分桶。
                items:
                  $ref: '#/components/schemas/HistoryBucket'
    HistoryResponse:
      type: object
      required: [response_time, currency, start, end, interval, items]
      description: '`POST /v1/prices/history` 的响应结构。'
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 查询范围的有效开始时间，向下取整到间隔边界。
        end:
          type: string
          format: date-time
          description: 查询范围的有效结束时间，向上取整到间隔边界。不包含该时间。
        interval:
          type: string
          enum:
            - 5m
            - 30m
            - 1h
            - 1d
          description: OHLC 分桶大小。
        items:
          type: object
          description: '`market_hash_name` 到 OHLC 时间序列的映射。'
          additionalProperties:
            $ref: '#/components/schemas/HistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 与成功结果一起返回的逐饰品失败（部分成功）。
      example:
        response_time: '2026-07-26T18:54:17.003186292Z'
        currency: USD
        start: '2026-07-20T00:00:00Z'
        end: '2026-07-23T00:00:00Z'
        interval: 1h
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            count: 72
            data:
              - bucket: '2026-07-20T00:00:00Z'
                buff:
                  open_ask: 115.16
                  high_ask: 115.16
                  low_ask: 115.16
                  close_ask: 115.16
                  ask_volume: 466
                  open_bid: 112.21
                  high_bid: 112.21
                  low_bid: 112.21
                  close_bid: 112.21
                  bid_volume: 42
                  sample_count: 75
                  open_time: '2026-07-20T00:00:51Z'
                  close_time: '2026-07-20T00:58:51Z'
                youpin:
                  open_ask: 113.54
                  high_ask: 113.54
                  low_ask: 113.54
                  close_ask: 113.54
                  ask_volume: 505
                  open_bid: 112.5
                  high_bid: 112.5
                  low_bid: 112.5
                  close_bid: 112.5
                  bid_volume: 64
                  sample_count: 12
                  open_time: '2026-07-20T00:04:07Z'
                  close_time: '2026-07-20T00:58:07Z'
                csfloat:
                  open_ask: 109.85
                  high_ask: 109.85
                  low_ask: 109.85
                  close_ask: 109.85
                  ask_volume: 229
                  open_bid: 107
                  high_bid: 107
                  low_bid: 107
                  close_bid: 107
                  sample_count: 60
                  open_time: '2026-07-20T00:00:25.313Z'
                  close_time: '2026-07-20T00:44:01.71Z'
                skinport:
                  open_ask: 122.71
                  high_ask: 122.71
                  low_ask: 122.71
                  close_ask: 122.71
                  ask_volume: 43
                  sample_count: 60
                  open_time: '2026-07-20T00:00:29.985Z'
                  close_time: '2026-07-20T00:59:29.996Z'
                steam:
                  open_ask: 161
                  high_ask: 161.62
                  low_ask: 161
                  close_ask: 161.62
                  ask_volume: 69
                  open_bid: 155.43
                  high_bid: 155.43
                  low_bid: 155.43
                  close_bid: 155.43
                  bid_volume: 2940
                  sample_count: 9
                  open_time: '2026-07-20T00:02:52.014Z'
                  close_time: '2026-07-20T00:54:22.006Z'
                c5game:
                  open_ask: 116.34
                  high_ask: 116.34
                  low_ask: 116.19
                  close_ask: 116.19
                  ask_volume: 147
                  open_bid: 232.98
                  high_bid: 232.98
                  low_bid: 232.98
                  close_bid: 232.98
                  sample_count: 12
                  open_time: '2026-07-20T00:02:49.997Z'
                  close_time: '2026-07-20T00:37:50.106Z'
    ItemLiquidityItem:
      type: object
      required: [market_hash_name]
      description: 单个饰品的流动性分档和预计售出时间。
      properties:
        market_hash_name:
          type: string
          description: Steam 市场哈希名称。
        liquidity:
          type: string
          enum: [unknown, extremely_illiquid, very_illiquid, illiquid, moderate, liquid, very_liquid, extremely_liquid]
          description: 重新计算的饰品流动性分档。
        estimated_sale_time:
          type: string
          enum: [under 1 hour, 1 - 2 hours, 2 - 6 hours, 6 - 12 hours, 12 - 24 hours, 1 - 2 days, 2 - 3 days, 3 - 4 days, 4 - 5 days, 5 - 7 days, 7 - 10 days, 10 - 14 days, 2 - 3 weeks, 3 - 4 weeks, 1 - 1.5 months, 1.5 - 2 months, 2+ months, unknown]
          description: 竞争性定价挂单售出的第 80 百分位预计等待时间。
        variants:
          type: object
          description: 按显示名称作为键的逐变体饰品流动性。
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, liquidity, estimated_sale_time]
            properties:
              market_hash_name:
                type: string
                description: 基础饰品的 `market_hash_name`。
              name:
                type: string
                description: 变体的完整 `market_hash_name`。
              display_name:
                type: string
                description: 人类可读的变体标签。
              version:
                type: string
                description: 稳定变体代码。
              liquidity:
                type: string
                enum: [unknown, extremely_illiquid, very_illiquid, illiquid, moderate, liquid, very_liquid, extremely_liquid]
              estimated_sale_time:
                type: string
                enum: [under 1 hour, 1 - 2 hours, 2 - 6 hours, 6 - 12 hours, 12 - 24 hours, 1 - 2 days, 2 - 3 days, 3 - 4 days, 4 - 5 days, 5 - 7 days, 7 - 10 days, 10 - 14 days, 2 - 3 weeks, 3 - 4 weeks, 1 - 1.5 months, 1.5 - 2 months, 2+ months, unknown]
    ItemLiquidityGetResponse:
      type: object
      required: [response_time, run_date, items]
      description: 全量饰品流动性快照。由 `GET /v1/liquidity/items` 返回。
      properties:
        response_time:
          type: string
          format: date-time
          description: 快照计算时间。
        run_date:
          type: string
          format: date
          description: 每日计算对应的 UTC 日期。
        items:
          type: object
          description: '`market_hash_name` 到饰品流动性数据的映射。'
          additionalProperties:
            $ref: '#/components/schemas/ItemLiquidityItem'
      example:
        response_time: '2026-07-26T00:00:29.508Z'
        run_date: '2026-07-26'
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            liquidity: extremely_liquid
            estimated_sale_time: 1 - 2 hours
    BUFFMarketFloatRange:
      type: object
      description: '`float` 或 `fade` 区间的数值范围。`min` 含，`max` 不含。'
      properties:
        min:
          type: number
          description: 下界（含）。
        max:
          type: number
          description: 上界（不含）。
    BUFFMarketFloatLatestBucket:
      type: object
      required: [bucket_id, bucket_type]
      description: 一个由 `bucket_type` 标识的最新 BUFF 磨损或渐变范围区间。
      properties:
        bucket_id:
          type: string
          description: 稳定的区间标识（例如 `base`、`float:0.15:0.18`、`variant:p2|float:0.00:0.01`）。
        bucket_type:
          type: string
          enum:
            - base
            - float
            - fade
            - float_fade
          description: |
            区间分层。
            - `base`：对整件饰品或变体的聚合。
            - `float`：按磨损区间切分（见 `float`）。
            - `fade`：按渐变百分比切分（见 `fade`）。
            - `float_fade`：磨损与渐变组合切分。
        float:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        fade:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        updated_at:
          type: string
          format: date-time
          description: BUFF 上次刷新该区间的时间。
        collected_at:
          type: string
          format: date-time
          description: cs2.sh 拉取该区间的时间。
        ask:
          type: number
          description: 该区间内最低挂单价（USD）。
        avg_ask:
          type: number
          description: 该区间内平均挂单价（USD）。
        bid:
          type: number
          description: BUFF 上的最高求购单价格（USD）。
        ask_volume:
          type: integer
          description: 该区间内在售饰品数量。
        bid_volume:
          type: integer
          description: 针对该区间的活跃求购单数量。
    BUFFMarketFloatHistoryPoint:
      type: object
      required: [bucket, open_time, close_time]
      description: BUFF 市场磨损/渐变区间历史中的单个 OHLC 观测点。
      properties:
        bucket:
          type: string
          format: date-time
          description: OHLC 间隔的开始时间（UTC 对齐到间隔边界）。
        updated_at:
          type: string
          format: date-time
          description: BUFF 在此间隔内最后一次刷新该区间的时间。
        collected_at:
          type: string
          format: date-time
          description: cs2.sh 在此间隔内抓取源数据行的时间。
        open_ask:
          type: number
          description: 间隔内首次观测的挂单价（USD）。
        high_ask:
          type: number
          description: 间隔内最高挂单价（USD）。
        low_ask:
          type: number
          description: 间隔内最低挂单价（USD）。
        close_ask:
          type: number
          description: 间隔内最后一次挂单价（USD）。
        open_avg_ask:
          type: number
          description: 间隔内首次观测的 `avg_ask` 值。
        high_avg_ask:
          type: number
          description: 间隔内最高 `avg_ask` 值。
        low_avg_ask:
          type: number
          description: 间隔内最低 `avg_ask` 值。
        close_avg_ask:
          type: number
          description: 间隔内最后一次 `avg_ask` 值。
        open_bid:
          type: number
          description: 间隔内首次观测的求购价（USD）。
        high_bid:
          type: number
          description: 间隔内最高求购价（USD）。
        low_bid:
          type: number
          description: 间隔内最低求购价（USD）。
        close_bid:
          type: number
          description: 间隔内最后一次求购价（USD）。
        ask_volume:
          type: integer
          description: 间隔内最后一次观测的挂单数量。
        bid_volume:
          type: integer
          description: 间隔内最后一次观测的求购单数量。
        open_time:
          type: string
          format: date-time
          description: 间隔内首次观测的时间戳。与 `bucket`（间隔边界）不同。
        close_time:
          type: string
          format: date-time
          description: 间隔内最后一次观测的时间戳。与 `bucket`（间隔边界）不同。
    BUFFMarketFloatHistoryBucket:
      type: object
      required: [bucket_id, bucket_type, data]
      description: 单个 BUFF 市场区间的 OHLC 历史。`data` 按时间顺序排列，每项对应一个间隔。
      properties:
        bucket_id:
          type: string
          description: 稳定的区间标识（例如 `fade:99:100`、`variant:p2|float:0.00:0.01`）。
        bucket_type:
          type: string
          enum:
            - base
            - float
            - fade
            - float_fade
          description: 区间分层，参见 `BUFFMarketFloatLatestBucket.bucket_type`。
        float:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        fade:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        data:
          type: array
          description: 该区间的 OHLC 观测，按时间顺序排列。
          items:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryPoint'
    BUFFMarketFloatVariant:
      type: object
      required: [market_hash_name, name, display_name, version, buckets]
      description: 单个饰品变体（Doppler / Gamma Doppler 相位或 Case Hardened 分层）的 BUFF 最新数据。
      properties:
        market_hash_name:
          type: string
          description: 基础饰品的 `market_hash_name`。完整变体名称见 `name`。
        name:
          type: string
          description: 该变体的完整 `market_hash_name`，例如 `★ M9 Bayonet | Doppler (Factory New) | Phase 1`。
        display_name:
          type: string
          description: 人类可读的变体标签（例如 `Phase 1`、`Ruby`、`Tier 1`）。
        version:
          type: string
          description: 稳定的变体代码。客户端代码应基于该字段分支。
        buckets:
          type: array
          description: 该变体的最新 BUFF 区间。
          items:
            $ref: '#/components/schemas/BUFFMarketFloatLatestBucket'
    BUFFMarketFloatHistoryVariant:
      type: object
      required: [market_hash_name, name, display_name, version, buckets]
      description: 单个饰品变体的 BUFF OHLC 历史。
      properties:
        market_hash_name:
          type: string
          description: 基础饰品的 `market_hash_name`。完整变体名称见 `name`。
        name:
          type: string
          description: 该变体的完整 `market_hash_name`，例如 `★ M9 Bayonet | Doppler (Factory New) | Phase 1`。
        display_name:
          type: string
          description: 人类可读的变体标签。
        version:
          type: string
          description: 稳定的变体代码。
        buckets:
          type: array
          description: 该变体每个区间的 OHLC 历史。
          items:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryBucket'
    BUFFMarketFloatItem:
      type: object
      required: [market_hash_name]
      description: 单件饰品的 BUFF 市场磨损/渐变数据。
      properties:
        market_hash_name:
          type: string
          description: 规范化的基础 `market_hash_name`。
        buckets:
          type: array
          description: 基础饰品挂单的最新 BUFF 区间。
          items:
            $ref: '#/components/schemas/BUFFMarketFloatLatestBucket'
        variants:
          type: object
          description: 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 BUFF 数据。按显示名称作为键（例如 `Phase 1`、`Ruby`、`Tier 1`）。
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatVariant'
    BUFFMarketFloatHistoryItem:
      type: object
      required: [market_hash_name]
      description: 单件饰品的 BUFF 市场磨损/渐变 OHLC 历史。
      properties:
        market_hash_name:
          type: string
          description: 规范化的基础 `market_hash_name`。
        buckets:
          type: array
          description: 基础饰品挂单各区间的 OHLC 历史。
          items:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryBucket'
        variants:
          type: object
          description: 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 OHLC 历史。按显示名称作为键。
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryVariant'
    BUFFMarketFloatLatestResponse:
      type: object
      required: [response_time, currency, items]
      description: 所有饰品的 BUFF 磨损与渐变范围快照。由 `GET /v1/market/buff/latest` 返回；所有价格均为 USD。
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        items:
          type: object
          description: '`market_hash_name` 到逐饰品 BUFF 数据的映射。'
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatItem'
      example:
        response_time: '2026-07-26T18:54:14.833093145Z'
        currency: USD
        items:
          AK-47 | Case Hardened (Field-Tested):
            market_hash_name: AK-47 | Case Hardened (Field-Tested)
            buckets:
              - bucket_id: base
                bucket_type: base
                updated_at: '2026-07-26T18:46:12Z'
                collected_at: '2026-07-26T18:50:54.164Z'
                ask: 213.23
                avg_ask: 216.98
                bid: 203.78
                ask_volume: 982
                bid_volume: 31
              - bucket_id: float:0.15:0.18
                bucket_type: float
                float:
                  min: 0.15
                  max: 0.18
                updated_at: '2026-07-26T18:46:12Z'
                collected_at: '2026-07-26T18:50:54.164Z'
                ask: 218.55
                avg_ask: 231.47
                bid: 203.78
                ask_volume: 219
                bid_volume: 10
            variants:
              Tier 1:
                market_hash_name: AK-47 | Case Hardened (Field-Tested)
                name: AK-47 | Case Hardened (Field-Tested) | Tier 1
                display_name: Tier 1
                version: t1
                buckets:
                  - bucket_id: variant:t1
                    bucket_type: base
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 1328.96
                    avg_ask: 2218.76
                    bid: 1077.98
                    ask_volume: 78
                    bid_volume: 13
                  - bucket_id: variant:t1|float:0.15:0.18
                    bucket_type: float
                    float:
                      min: 0.15
                      max: 0.18
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 2584.21
                    avg_ask: 12532.95
                    bid: 1077.98
                    ask_volume: 12
                    bid_volume: 15
                  - bucket_id: variant:t1|float:0.18:0.21
                    bucket_type: float
                    float:
                      min: 0.18
                      max: 0.21
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 1609.44
                    avg_ask: 14470.85
                    bid: 1079.46
                    ask_volume: 11
                    bid_volume: 23
                  - bucket_id: variant:t1|float:0.21:0.24
                    bucket_type: float
                    float:
                      min: 0.21
                      max: 0.24
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 2215.04
                    avg_ask: 33480.73
                    bid: 1079.46
                    ask_volume: 9
                    bid_volume: 23
                  - bucket_id: variant:t1|float:0.24:0.27
                    bucket_type: float
                    float:
                      min: 0.24
                      max: 0.27
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 2953.23
                    avg_ask: 19841.46
                    bid: 1079.46
                    ask_volume: 7
                    bid_volume: 23
                  - bucket_id: variant:t1|float:0.27:0.38
                    bucket_type: float
                    float:
                      min: 0.27
                      max: 0.38
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 1328.96
                    avg_ask: 3056.22
                    bid: 1079.46
                    ask_volume: 39
                    bid_volume: 16
              Tier 2:
                market_hash_name: AK-47 | Case Hardened (Field-Tested)
                name: AK-47 | Case Hardened (Field-Tested) | Tier 2
                display_name: Tier 2
                version: t2
                buckets:
                  - bucket_id: variant:t2
                    bucket_type: base
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 389.77
                    avg_ask: 398.86
                    bid: 366.22
                    ask_volume: 235
                    bid_volume: 14
                  - bucket_id: variant:t2|float:0.15:0.18
                    bucket_type: float
                    float:
                      min: 0.15
                      max: 0.18
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 443.01
                    avg_ask: 521.14
                    bid: 366.22
                    ask_volume: 49
                    bid_volume: 16
                  - bucket_id: variant:t2|float:0.18:0.21
                    bucket_type: float
                    float:
                      min: 0.18
                      max: 0.21
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 407.57
                    avg_ask: 515.91
                    bid: 366.22
                    ask_volume: 38
                    bid_volume: 17
                  - bucket_id: variant:t2|float:0.21:0.24
                    bucket_type: float
                    float:
                      min: 0.21
                      max: 0.24
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 394.28
                    avg_ask: 672.67
                    bid: 366.22
                    ask_volume: 18
                    bid_volume: 16
                  - bucket_id: variant:t2|float:0.24:0.27
                    bucket_type: float
                    float:
                      min: 0.24
                      max: 0.27
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 389.77
                    avg_ask: 449.59
                    bid: 366.22
                    ask_volume: 32
                    bid_volume: 15
                  - bucket_id: variant:t2|float:0.27:0.38
                    bucket_type: float
                    float:
                      min: 0.27
                      max: 0.38
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 389.85
                    avg_ask: 408.05
                    bid: 366.22
                    ask_volume: 98
                    bid_volume: 15
              Tier 3:
                market_hash_name: AK-47 | Case Hardened (Field-Tested)
                name: AK-47 | Case Hardened (Field-Tested) | Tier 3
                display_name: Tier 3
                version: t3
                buckets:
                  - bucket_id: variant:t3
                    bucket_type: base
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 216.26
                    avg_ask: 235.87
                    bid: 203.78
                    ask_volume: 295
                    bid_volume: 10
                  - bucket_id: variant:t3|float:0.15:0.18
                    bucket_type: float
                    float:
                      min: 0.15
                      max: 0.18
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 221.36
                    avg_ask: 252.9
                    bid: 203.78
                    ask_volume: 65
                    bid_volume: 10
                  - bucket_id: variant:t3|float:0.18:0.21
                    bucket_type: float
                    float:
                      min: 0.18
                      max: 0.21
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 236.12
                    avg_ask: 300.55
                    bid: 203.78
                    ask_volume: 41
                    bid_volume: 10
                  - bucket_id: variant:t3|float:0.21:0.24
                    bucket_type: float
                    float:
                      min: 0.21
                      max: 0.24
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 233.02
                    avg_ask: 276.7
                    bid: 203.78
                    ask_volume: 41
                    bid_volume: 10
                  - bucket_id: variant:t3|float:0.24:0.27
                    bucket_type: float
                    float:
                      min: 0.24
                      max: 0.27
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 248.08
                    avg_ask: 288.19
                    bid: 203.78
                    ask_volume: 38
                    bid_volume: 10
                  - bucket_id: variant:t3|float:0.27:0.38
                    bucket_type: float
                    float:
                      min: 0.27
                      max: 0.38
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 216.26
                    avg_ask: 246.05
                    bid: 203.78
                    ask_volume: 110
                    bid_volume: 10
              Tier 4:
                market_hash_name: AK-47 | Case Hardened (Field-Tested)
                name: AK-47 | Case Hardened (Field-Tested) | Tier 4
                display_name: Tier 4
                version: t4
                buckets:
                  - bucket_id: variant:t4
                    bucket_type: base
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 213.23
                    avg_ask: 217.52
                    bid: 203.78
                    ask_volume: 362
                    bid_volume: 10
                  - bucket_id: variant:t4|float:0.15:0.18
                    bucket_type: float
                    float:
                      min: 0.15
                      max: 0.18
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 218.55
                    avg_ask: 233.7
                    bid: 203.78
                    ask_volume: 91
                    bid_volume: 10
                  - bucket_id: variant:t4|float:0.18:0.21
                    bucket_type: float
                    float:
                      min: 0.18
                      max: 0.21
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 221.5
                    avg_ask: 234.11
                    bid: 203.78
                    ask_volume: 59
                    bid_volume: 10
                  - bucket_id: variant:t4|float:0.21:0.24
                    bucket_type: float
                    float:
                      min: 0.21
                      max: 0.24
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 213.23
                    avg_ask: 240.46
                    bid: 203.78
                    ask_volume: 41
                    bid_volume: 10
                  - bucket_id: variant:t4|float:0.24:0.27
                    bucket_type: float
                    float:
                      min: 0.24
                      max: 0.27
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 216.52
                    avg_ask: 267.28
                    bid: 203.78
                    ask_volume: 33
                    bid_volume: 10
                  - bucket_id: variant:t4|float:0.27:0.38
                    bucket_type: float
                    float:
                      min: 0.27
                      max: 0.38
                    updated_at: '2026-07-26T18:46:12Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 213.38
                    avg_ask: 220.17
                    bid: 203.78
                    ask_volume: 138
                    bid_volume: 10
          ★ M9 Bayonet | Doppler (Factory New):
            market_hash_name: ★ M9 Bayonet | Doppler (Factory New)
            variants:
              Phase 2:
                market_hash_name: ★ M9 Bayonet | Doppler (Factory New)
                name: ★ M9 Bayonet | Doppler (Factory New) | Phase 2
                display_name: Phase 2
                version: p2
                buckets:
                  - bucket_id: variant:p2
                    bucket_type: base
                    updated_at: '2026-07-26T18:46:27Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 1321.49
                    avg_ask: 1327.42
                    bid: 1281.77
                    ask_volume: 261
                    bid_volume: 22
                  - bucket_id: variant:p2|float:0.00:0.01
                    bucket_type: float
                    float:
                      min: 0
                      max: 0.01
                    updated_at: '2026-07-26T18:46:27Z'
                    collected_at: '2026-07-26T18:50:54.164Z'
                    ask: 1336.26
                    avg_ask: 1365.19
                    bid: 1284.72
                    ask_volume: 60
                    bid_volume: 25
    BUFFMarketFloatHistoryRequest:
      type: object
      required:
        - items
        - start
      properties:
        items:
          type: array
          items:
            type: string
          maxItems: 100
          description: '`market_hash_name` 值列表（最多 100 个）'
          example:
            - ★ Bayonet | Fade (Factory New)
            - AK-47 | Case Hardened (Field-Tested)
        start:
          type: string
          description: 开始日期/时间（YYYY-MM-DD 或 RFC3339）
          example: '2026-07-20'
        end:
          type: string
          description: 结束日期/时间（YYYY-MM-DD 或 RFC3339）。默认现在。
          example: '2026-07-23'
        interval:
          type: string
          enum:
            - 30m
            - 1h
            - 1d
          default: 30m
          example: 1h
    BUFFMarketFloatHistoryResponse:
      type: object
      required: [response_time, currency, start, end, interval, items]
      description: 由 `POST /v1/market/buff/history` 返回的响应。每个请求的 BUFF 市场磨损/渐变区间都会带有 OHLC 历史。
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 查询区间的有效起点，向下对齐到间隔边界。
        end:
          type: string
          format: date-time
          description: 查询区间的有效终点，向上对齐到间隔边界。不含。
        interval:
          type: string
          enum:
            - 30m
            - 1h
            - 1d
          description: OHLC 分桶粒度。
        items:
          type: object
          description: '`market_hash_name` 到逐饰品 BUFF 历史的映射。'
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 部分成功响应中按饰品的错误列表。
      example:
        response_time: '2026-07-26T18:54:21.429446677Z'
        currency: USD
        start: '2026-07-20T00:00:00Z'
        end: '2026-07-23T00:00:00Z'
        interval: 1h
        items:
          ★ Bayonet | Fade (Factory New):
            market_hash_name: ★ Bayonet | Fade (Factory New)
            buckets:
              - bucket_id: base
                bucket_type: base
                data:
                  - bucket: '2026-07-20T00:00:00Z'
                    updated_at: '2026-07-20T00:46:24Z'
                    collected_at: '2026-07-20T00:50:57.483Z'
                    open_ask: 371.36
                    high_ask: 371.57
                    low_ask: 371.36
                    close_ask: 371.57
                    open_avg_ask: 379.74
                    high_avg_ask: 379.96
                    low_avg_ask: 379.74
                    close_avg_ask: 379.96
                    open_bid: 359.57
                    high_bid: 359.78
                    low_bid: 359.57
                    close_bid: 359.78
                    ask_volume: 177
                    bid_volume: 23
                    open_time: '2026-07-20T00:00:53.231Z'
                    close_time: '2026-07-20T00:50:57.483Z'
    SteamOrderbookTop:
      type: object
      description: Steam 订单簿的最优卖单/买单（盘口顶部）。某一侧缺失时对应字段为 `null`。
      required:
        - ask
        - ask_volume
        - bid
        - bid_volume
      properties:
        ask:
          type: [number, "null"]
          description: 最优卖单 USD 价格；缺失时为 `null`。
        ask_volume:
          type: [integer, "null"]
          description: Steam 卖单总数量；缺失时为 `null`。
        bid:
          type: [number, "null"]
          description: 最优买单 USD 价格；缺失时为 `null`。
        bid_volume:
          type: [integer, "null"]
          description: Steam 买单总数量；缺失时为 `null`。
    SteamOrderbookDepthSide:
      type: object
      description: 订单簿某一侧的列式深度。`prices[i]` 与 `volumes[i]` 一一对应；每个 `volume` 是该价格上的数量，不是累计数量。
      required:
        - prices
        - volumes
      properties:
        prices:
          type: array
          description: USD 十进制价格。卖单升序，买单降序。
          items:
            type: number
        volumes:
          type: array
          description: 每个对应价格上的数量。
          items:
            type: integer
    SteamOrderbookDepth:
      type: object
      description: 列式表示的全深度 Steam 订单簿档位。
      required:
        - ask_levels
        - bid_levels
        - asks
        - bids
      properties:
        ask_levels:
          type: integer
          description: '`asks` 中的卖单档位数量。'
        bid_levels:
          type: integer
          description: '`bids` 中的买单档位数量。'
        asks:
          $ref: '#/components/schemas/SteamOrderbookDepthSide'
        bids:
          $ref: '#/components/schemas/SteamOrderbookDepthSide'
    SteamOrderbookItem:
      type: object
      description: 单个常规饰品的最新全深度 Steam 订单簿。
      required:
        - updated_at
        - collected_at
        - top
        - depth
      properties:
        updated_at:
          type: string
          format: date-time
          description: Steam 最后更新该订单簿的时间。
        collected_at:
          type: string
          format: date-time
          description: cs2.sh 采集该订单簿的时间。
        top:
          $ref: '#/components/schemas/SteamOrderbookTop'
        depth:
          $ref: '#/components/schemas/SteamOrderbookDepth'
    SteamOrderbookLatestResponse:
      type: object
      description: 所有被追踪常规饰品的最新 Steam 订单簿快照。由 `GET /v1/market/steam/latest` 返回；不支持变体。
      required:
        - response_time
        - currency
        - as_of
        - items
      properties:
        response_time:
          type: string
          format: date-time
          description: 此快照响应的生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        as_of:
          type: string
          format: date-time
          description: 整个快照中最新的 `updated_at`。
        items:
          type: object
          description: 具有当前订单簿数据的常规饰品，按 `market_hash_name` 键控。
          additionalProperties:
            $ref: '#/components/schemas/SteamOrderbookItem'
      example:
        response_time: '2026-07-26T18:54:14.123567967Z'
        currency: USD
        as_of: '2026-07-26T18:53:53.202Z'
        items:
          USP-S | Printstream (Factory New):
            updated_at: '2026-07-26T18:52:21.42Z'
            collected_at: '2026-07-26T18:52:56.46Z'
            top:
              ask: 169.14
              ask_volume: 70
              bid: 155.05
              bid_volume: 2951
            depth:
              ask_levels: 2
              bid_levels: 2
              asks:
                prices: [169.14, 169.4]
                volumes: [1, 1]
              bids:
                prices: [155.05, 154.88]
                volumes: [1, 1]
    SteamOrderbookHistoryRequest:
      type: object
      required:
        - items
        - start
        - interval
      properties:
        items:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: 常规 `market_hash_name` 值列表（最多 100 个）。不支持变体。
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: 开始日期/时间（YYYY-MM-DD 或 RFC3339），包含。
          example: '2026-07-20'
        end:
          type: string
          description: 结束日期/时间（YYYY-MM-DD 或 RFC3339），不含。默认现在。
          example: '2026-07-23'
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: 分桶间隔。`1h` 最多 90 天；`1d` 不限。
          example: 1h
    SteamOrderbookHistoryPoint:
      type: object
      description: 一个分桶内最新的全深度 Steam 订单簿快照。这不是 OHLC 数据。
      required:
        - bucket
        - updated_at
        - collected_at
        - top
        - depth
      properties:
        bucket:
          type: string
          format: date-time
          description: UTC 分桶开始时间。
        updated_at:
          type: string
          format: date-time
          description: Steam 最后更新该分桶所代表订单簿的时间。
        collected_at:
          type: string
          format: date-time
          description: cs2.sh 采集该分桶所代表订单簿的时间。
        top:
          $ref: '#/components/schemas/SteamOrderbookTop'
        depth:
          $ref: '#/components/schemas/SteamOrderbookDepth'
    SteamOrderbookHistoryItem:
      type: object
      description: 单个常规饰品的 Steam 订单簿分桶快照。不返回变体。
      required:
        - count
        - data
      properties:
        count:
          type: integer
          description: '`data` 中的数据点数量。'
        data:
          type: array
          description: 按 `bucket` 升序排列的数据点。
          items:
            $ref: '#/components/schemas/SteamOrderbookHistoryPoint'
    SteamOrderbookHistoryResponse:
      type: object
      description: '`POST /v1/market/steam/history` 的响应结构。有合法常规饰品但无数据时会从 `items` 中省略；如果所有合法常规饰品均无数据，则 `items` 为空。'
      required:
        - response_time
        - currency
        - start
        - end
        - interval
        - items
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 规范化 UTC 起点，包含。
        end:
          type: string
          format: date-time
          description: 规范化 UTC 终点，不含。
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: 请求的分桶间隔。
        items:
          type: object
          description: '`market_hash_name` 到返回订单簿历史的映射。'
          additionalProperties:
            $ref: '#/components/schemas/SteamOrderbookHistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 部分成功响应中按饰品的错误列表。
      example:
        response_time: '2026-07-26T18:54:23.061441059Z'
        currency: USD
        start: '2026-07-20T00:00:00Z'
        end: '2026-07-23T00:00:00Z'
        interval: 1h
        items:
          USP-S | Printstream (Factory New):
            count: 72
            data:
              - bucket: '2026-07-20T00:00:00Z'
                updated_at: '2026-07-20T00:54:22.006Z'
                collected_at: '2026-07-20T00:55:13.298Z'
                top:
                  ask: 161.62
                  ask_volume: 69
                  bid: 155.43
                  bid_volume: 2940
                depth:
                  ask_levels: 1
                  bid_levels: 1
                  asks:
                    prices: [161.62]
                    volumes: [1]
                  bids:
                    prices: [155.43]
                    volumes: [1]
    ArchiveSteamRequest:
      type: object
      required:
        - items
        - start
        - interval
      properties:
        items:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: 常规 `market_hash_name` 值列表（最多 100 个）。不支持变体。
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: 开始日期/时间（YYYY-MM-DD 或 RFC3339），包含。
          example: '2025-01-01'
        end:
          type: string
          description: 结束日期/时间（YYYY-MM-DD 或 RFC3339），不含。默认现在。
          example: '2025-02-01'
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: 原生 Steam 分桶间隔。无公开最大日期范围。
          example: 1d
    ArchiveSteamBucket:
      type: object
      description: 一个原生 Steam 成交历史分桶。`price` 是 Steam 成交中位价，`volume` 是 purchases 数量。
      required:
        - bucket
        - price
        - volume
      properties:
        bucket:
          type: string
          format: date-time
          description: 原生 Steam 分桶开始时间。
        price:
          type: [number, "null"]
          description: Steam USD 成交中位价。
        volume:
          type: [integer, "null"]
          description: Steam 报告的购买次数。
    ArchiveSteamItem:
      type: object
      description: 单个常规饰品的原生 Steam 成交历史分桶。不返回变体。
      required:
        - market_hash_name
        - count
        - data
      properties:
        market_hash_name:
          type: string
          description: 规范化的常规 Steam market hash name。
        count:
          type: integer
          description: '`data` 中的分桶数量。'
        data:
          type: array
          description: 按 `bucket` 升序排列的分桶。
          items:
            $ref: '#/components/schemas/ArchiveSteamBucket'
    ArchiveSteamResponse:
      type: object
      description: '`POST /v1/archive/steam` 的响应结构。合法常规饰品无数据时返回饰品级 `not_in_archive`；如果每个合法常规饰品均无数据，端点返回 `404 not_found`。'
      required:
        - response_time
        - currency
        - start
        - end
        - interval
        - items
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 规范化 UTC 起点，包含。
        end:
          type: string
          format: date-time
          description: 规范化 UTC 终点，不含。
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: 每个返回分桶对应的请求的原生 Steam 间隔。
        items:
          type: object
          description: '`market_hash_name` 到原生 Steam 成交历史分桶的映射。'
          additionalProperties:
            $ref: '#/components/schemas/ArchiveSteamItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 部分成功响应中按饰品的错误列表。
      example:
        response_time: '2026-07-26T18:54:20.110090345Z'
        currency: USD
        start: '2025-01-01T00:00:00Z'
        end: '2025-02-01T00:00:00Z'
        interval: 1d
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            count: 31
            data:
              - bucket: '2025-01-01T00:00:00Z'
                price: 150.23
                volume: 7
    ItemError:
      type: object
      required: [item, code, message]
      description: 部分成功响应中特定饰品的错误
      properties:
        item:
          type: string
          description: 失败的请求饰品名称
        code:
          type: string
          enum:
            - unknown_item
            - not_in_cache
            - invalid_format
            - not_in_archive
            - unsupported_variant
            - unsupported_source
          description: 错误代码
        message:
          type: string
          description: 人类可读错误消息
    ArchiveCSFloatRequest:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
          maxItems: 100
          description: '`market_hash_name` 值列表（最多 100 个）'
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: 开始日期（YYYY-MM-DD 或 RFC3339）。默认 2020-01-01。
          example: '2024-01-01'
        end:
          type: string
          description: 结束日期（YYYY-MM-DD 或 RFC3339）。默认现在。
          example: '2026-07-26'
    ArchiveCSFloatBucket:
      type: object
      required: [date, price, volume]
      description: CSFloat 上一天的成交数据。
      properties:
        date:
          type: string
          description: '`YYYY-MM-DD` 格式的日期（UTC）。'
        price:
          type: [number, "null"]
          description: 当天所有成交价格的算术平均值（USD）。
        volume:
          type: integer
          description: 当天成交次数。
    ArchiveCSFloatItem:
      type: object
      required: [market_hash_name, count, data]
      description: 单个饰品的 CSFloat 成交时间序列。
      properties:
        market_hash_name:
          type: string
          description: Steam 市场哈希名称。
        count:
          type: integer
          description: 有数据的天数
        data:
          type: array
          description: 按时间顺序排列的每日成交聚合。
          items:
            $ref: '#/components/schemas/ArchiveCSFloatBucket'
        variants:
          type: object
          description: 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 CSFloat 成交时间序列。按显示名称作为键。
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, count, data]
            properties:
              market_hash_name:
                type: string
                description: 基础饰品的 `market_hash_name`。
              name:
                type: string
                description: 变体的完整 `market_hash_name`。
              display_name:
                type: string
                description: 人类可读的变体标签。
              version:
                type: string
                description: 稳定变体代码。
              count:
                type: integer
                description: 此变体有数据的天数。
              data:
                type: array
                description: 按时间顺序排列的每日成交聚合。
                items:
                  $ref: '#/components/schemas/ArchiveCSFloatBucket'
    ArchiveCSFloatResponse:
      type: object
      required: [response_time, currency, start, end, items]
      description: '`POST /v1/archive/csfloat` 的响应结构。'
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 查询范围的有效开始时间，向下取整到日边界。
        end:
          type: string
          format: date-time
          description: 查询范围的有效结束时间，向上取整到日边界。不包含该时间。
        items:
          type: object
          description: '`market_hash_name` 到 CSFloat 成交时间序列的映射。'
          additionalProperties:
            $ref: '#/components/schemas/ArchiveCSFloatItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 与成功结果一起返回的逐饰品失败（部分成功）。
      example:
        response_time: '2026-07-26T18:54:19.632716841Z'
        currency: USD
        start: '2026-04-27T00:00:00Z'
        end: '2026-07-25T00:00:00Z'
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            count: 89
            data:
              - date: '2026-04-27'
                price: 149.76
                volume: 8
              - date: '2026-04-28'
                price: 189.81
                volume: 10
    ArchiveYoupinRequest:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
          maxItems: 100
          description: '`market_hash_name` 值列表（最多 100 个）'
          example:
            - ★ Karambit | Doppler (Factory New)
        start:
          type: string
          description: 开始日期（YYYY-MM-DD 或 RFC3339）。默认 180 天前。向下取整到整点。
          example: '2026-01-29'
        end:
          type: string
          description: 结束日期（YYYY-MM-DD 或 RFC3339）。默认现在。向上取整到整点。
          example: '2026-07-28'
    ArchiveYoupinPoint:
      type: object
      required: [bucket, time, price]
      description: Youpin 上的一笔成交。Youpin 对每个抽样分桶只保留一笔成交，因此点是一笔真实成交，不是聚合值。抽样间隔由序列的键承载，绝不作为点上的字段。
      properties:
        bucket:
          type: string
          format: date-time
          description: 该点所代表的上游抽样分桶的起点，宽度与所在序列一致。
        time:
          type: string
          format: date-time
          description: 分桶内的实际成交时间。
        price:
          type: [number, "null"]
          description: 成交价（USD），按成交日期各自的历史汇率由 CNY 换算；当该日期的汇率无法解析时为 `null`。
    ArchiveYoupinSeries:
      type: object
      required: [count, data]
      description: 单一上游抽样间隔下的一条独立 Youpin 成交序列，只含 `count` 和 `data`。序列之间绝不拼接、求和或交错。
      properties:
        count:
          type: integer
          description: 该序列中的点数量，等于 `data` 的长度。这不是成交量；`count` 为 0 且 `data` 为空表示该间隔被观测过且窗口内无成交。
        data:
          type: array
          description: 该间隔下的成交，按分桶排序。
          items:
            $ref: '#/components/schemas/ArchiveYoupinPoint'
    ArchiveYoupinItem:
      type: object
      required: [market_hash_name, intervals]
      description: 单个饰品的 Youpin 成交历史，按上游抽样间隔各提供一条独立序列。
      properties:
        market_hash_name:
          type: string
          description: Steam 市场哈希名称。
        intervals:
          type: object
          description: 按上游抽样间隔键控的独立序列，按 `1h`、`4h`、`12h` 顺序输出。只有该间隔在请求窗口内被观测过时键才存在，因此仅为承载所请求变体而存在的条目返回 `{}`。
          properties:
            1h:
              $ref: '#/components/schemas/ArchiveYoupinSeries'
            4h:
              $ref: '#/components/schemas/ArchiveYoupinSeries'
            12h:
              $ref: '#/components/schemas/ArchiveYoupinSeries'
        variants:
          type: object
          description: 具备 Doppler 或 Gamma Doppler 相位或 Case Hardened 分层的饰品的按变体 Youpin 成交历史。以显示名称为键，为空时省略。变体序列绝不回退到基础饰品历史。
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, intervals]
            properties:
              market_hash_name:
                type: string
                description: 基础饰品的 `market_hash_name`。
              name:
                type: string
                description: 变体的完整 `market_hash_name`。
              display_name:
                type: string
                description: 人类可读的变体标签。
              version:
                type: string
                description: 稳定的变体代码。
              intervals:
                type: object
                description: 该变体的独立序列，按上游抽样间隔键控，规则与饰品的 `intervals` 相同。
                properties:
                  1h:
                    $ref: '#/components/schemas/ArchiveYoupinSeries'
                  4h:
                    $ref: '#/components/schemas/ArchiveYoupinSeries'
                  12h:
                    $ref: '#/components/schemas/ArchiveYoupinSeries'
    ArchiveYoupinResponse:
      type: object
      required: [response_time, currency, start, end, items]
      description: '`POST /v1/archive/youpin` 的响应结构。'
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 查询范围的实际起点，向下取整到 1h 边界。
        end:
          type: string
          format: date-time
          description: 查询范围的实际终点，向上取整到 1h 边界。不含。
        items:
          type: object
          description: '`market_hash_name` 到 Youpin 成交序列的映射。'
          additionalProperties:
            $ref: '#/components/schemas/ArchiveYoupinItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 与成功结果并存的按饰品失败（部分成功）。
      example:
        response_time: '2026-07-28T16:20:41.318204951Z'
        currency: USD
        start: '2026-01-29T00:00:00Z'
        end: '2026-07-28T00:00:00Z'
        items:
          ★ Karambit | Doppler (Factory New):
            market_hash_name: ★ Karambit | Doppler (Factory New)
            intervals:
              1h:
                count: 120
                data:
                  - bucket: '2026-07-21T16:00:00Z'
                    time: '2026-07-21T16:52:38.307Z'
                    price: 1314.88
                  - bucket: '2026-07-21T23:00:00Z'
                    time: '2026-07-21T23:42:05.008Z'
                    price: 1920.6
              4h:
                count: 180
                data:
                  - bucket: '2026-06-27T16:00:00Z'
                    time: '2026-06-27T18:37:02.696Z'
                    price: 1971.09
                  - bucket: '2026-06-27T20:00:00Z'
                    time: '2026-06-27T23:59:41.06Z'
                    price: 1995.59
              12h:
                count: 353
                data:
                  - bucket: '2026-01-29T16:00:00Z'
                    time: '2026-01-30T03:34:33.138Z'
                    price: 2256.76
                  - bucket: '2026-01-30T16:00:00Z'
                    time: '2026-01-31T03:51:57.426Z'
                    price: 1438.64
            variants:
              Phase 2:
                market_hash_name: ★ Karambit | Doppler (Factory New)
                name: ★ Karambit | Doppler (Factory New) | Phase 2
                display_name: Phase 2
                version: p2
                intervals:
                  12h:
                    count: 356
                    data:
                      - bucket: '2026-01-29T04:00:00Z'
                        time: '2026-01-29T15:46:01.526Z'
                        price: 2296.22
    ArchiveHistoryRequest:
      type: object
      required:
        - items
        - start
      properties:
        items:
          type: array
          items:
            type: string
          maxItems: 100
          description: '`market_hash_name` 值列表（最多 100 个）'
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: 开始日期（YYYY-MM-DD 或 RFC3339）
          example: '2024-01-01'
        end:
          type: string
          description: 结束日期（YYYY-MM-DD 或 RFC3339）。默认现在。
          example: '2026-07-26'
        sources:
          type: array
          items:
            type: string
            enum:
              - aggregate
              - buff
              - youpin
              - c5game
          description: 过滤到指定来源。默认：仅 aggregate。
          example:
            - aggregate
            - buff
        interval:
          type: string
          enum:
            - 1h
            - 1d
          default: 1d
          description: 聚合间隔
          example: 1d
    ArchiveHistoryPlatformData:
      type: object
      required: [time, ask, ask_volume, bid, bid_volume, sample_count]
      description: 归档分桶内的逐平台价格数据。`hourly_volume` 和 `total_supply` 仅在 `aggregate` 平台上填充。
      properties:
        time:
          type: string
          format: date-time
          description: 分桶内最后一次观测的实际时间戳。不同于分桶边界。
        ask:
          type: [number, "null"]
          description: 分桶内最后观测到的 ask 价格（USD）。
        ask_volume:
          type: [integer, "null"]
          description: 最后观测到的在售饰品数量。
        bid:
          type: [number, "null"]
          description: 分桶内最后观测到的 bid 价格（USD）。
        bid_volume:
          type: [integer, "null"]
          description: 最后观测到的求购单数量。
        hourly_volume:
          type: [number, "null"]
          description: 聚合交易量指标（仅 `aggregate` 平台）。
        total_supply:
          type: [number, "null"]
          description: 总市场供应量指标（仅 `aggregate` 平台）。
        sample_count:
          type: integer
          description: 聚合到此分桶的观测数量。
    ArchiveHistoryBucket:
      type: object
      required: [bucket]
      description: 单个归档时间分桶。只有当该平台在此分桶中存在数据时，对应平台键才会出现。
      properties:
        bucket:
          type: string
          format: date-time
          description: 时间分桶的开始时间（UTC 对齐到间隔边界）。
        aggregate:
          $ref: '#/components/schemas/ArchiveHistoryPlatformData'
        buff:
          $ref: '#/components/schemas/ArchiveHistoryPlatformData'
        youpin:
          $ref: '#/components/schemas/ArchiveHistoryPlatformData'
        c5game:
          $ref: '#/components/schemas/ArchiveHistoryPlatformData'
    ArchiveHistoryItem:
      type: object
      required: [market_hash_name, count, data]
      description: 单个饰品的长期归档时间序列。
      properties:
        market_hash_name:
          type: string
          description: Steam 市场哈希名称。
        count:
          type: integer
          description: 有数据的分桶数量。
        data:
          type: array
          description: 按时间顺序排列的归档分桶。
          items:
            $ref: '#/components/schemas/ArchiveHistoryBucket'
        variants:
          type: object
          description: 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体归档时间序列。按显示名称作为键。
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, count, data]
            properties:
              market_hash_name:
                type: string
                description: 基础饰品的 `market_hash_name`。
              name:
                type: string
                description: 变体的完整 `market_hash_name`。
              display_name:
                type: string
                description: 人类可读的变体标签。
              version:
                type: string
                description: 稳定变体代码。
              count:
                type: integer
                description: 此变体有数据的分桶数量。
              data:
                type: array
                description: 按时间顺序排列的归档分桶。
                items:
                  $ref: '#/components/schemas/ArchiveHistoryBucket'
    ArchiveHistoryResponse:
      type: object
      required: [response_time, currency, start, end, interval, items]
      description: '`POST /v1/archive/history` 的响应结构。'
      properties:
        response_time:
          type: string
          format: date-time
          description: 响应生成时间。
        currency:
          type: string
          description: 货币代码（始终为 `USD`）。
        start:
          type: string
          format: date-time
          description: 查询范围的有效开始时间，向下取整到间隔边界。
        end:
          type: string
          format: date-time
          description: 查询范围的有效结束时间，向上取整到间隔边界。不包含该时间。
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: 归档分桶大小。
        items:
          type: object
          description: '`market_hash_name` 到归档时间序列的映射。'
          additionalProperties:
            $ref: '#/components/schemas/ArchiveHistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: 与成功结果一起返回的逐饰品失败（部分成功）。
      example:
        response_time: '2026-07-26T18:54:19.138233339Z'
        currency: USD
        start: '2026-04-27T00:00:00Z'
        end: '2026-07-25T00:00:00Z'
        interval: 1d
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            count: 89
            data:
              - bucket: '2026-04-27T00:00:00Z'
                aggregate:
                  time: '2026-04-27T23:59:07Z'
                  ask: 130.05
                  ask_volume: 1225
                  bid: 130.19
                  bid_volume: 133
                  hourly_volume: 27
                  total_supply: 31291
                  sample_count: 24
                buff:
                  time: '2026-04-27T23:53:24Z'
                  ask: 133.12
                  ask_volume: 405
                  bid: 130.19
                  bid_volume: 45
                  sample_count: 24
                youpin:
                  time: '2026-04-27T23:59:07Z'
                  ask: 130.05
                  ask_volume: 510
                  bid: 128.59
                  bid_volume: 63
                  sample_count: 24
                c5game:
                  time: '2026-04-27T23:57:07Z'
                  ask: 132.21
                  ask_volume: 139
                  bid: 213.58
                  bid_volume: 24
                  sample_count: 24
    SchemaRarity:
      type: object
      description: 一个稀有度分层。列在顶层 `rarities` 数组中，并由饰品层的 `rarity` 引用。
      required:
        - key
        - name
        - tier
        - color
      properties:
        key:
          type: string
          description: 稳定的稀有度键（例如 `ancient`、`legendary`）。
        name:
          type: string
          description: 显示名称（例如 `Covert`、`Classified`）。
        tier:
          type: integer
          description: 数值稀有度分层，随稀有度递增。
        color:
          type: string
          description: 该稀有度的十六进制颜色。
    SchemaCollection:
      type: object
      description: 收藏品元数据。在顶层 `collections` 映射中按收藏品名称键控。
      required:
        - name
        - kind
      properties:
        name:
          type: string
          description: 收藏品名称。
        kind:
          type: string
          description: 收藏品类型（例如 `weapon`、`sticker`）。
        release_date:
          type: string
          description: 发布日期（`YYYY-MM-DD`），已知时提供。饰品的发布日期即其收藏品的发布日期；饰品带有 `collections`，请据此关联，而不要指望每件饰品自带日期。
        released_at:
          type: string
          description: 发布该收藏品的 Valve 公告的确切发布时刻（RFC 3339 UTC）。仅在该公告已知时提供。
        update_name:
          type: string
          description: Valve 对该次更新的自有名称，例如 `Season 5, Armory, and More`。
        announcement_url:
          type: string
          description: 该次更新的规范 Steam 公告地址。
        image:
          type: string
          description: 由 `cs2.sh` 提供的自有图片 URL，可用时提供。
        steam_image:
          type: string
          description: 可选的 Valve Economy/static 官方图片 URL；仅在精确来源已得到独立证明时提供。
    SchemaItemVariant:
      type: object
      description: 列在基础饰品 `variants` 下的一个 Doppler / Gamma Doppler 相位或 Case Hardened 分层。
      required:
        - market_hash_name
        - family
        - name
        - image
      properties:
        market_hash_name:
          type: string
          description: 完整的变体 `market_hash_name`。
        family:
          type: string
          enum:
            - doppler
            - gamma_doppler
            - case_hardened
          description: 变体家族。
        name:
          type: string
          description: 变体名称（例如 `Phase 2`、`Ruby`、`Tier 1`）。
        phase:
          type: string
          description: 相位或宝石名称。Case Hardened 会省略。
        color:
          type: string
          description: 十六进制强调色。Case Hardened 会省略。
        paint_index:
          type: integer
          description: 该变体的涂装索引。
        image:
          type: string
          description: '`cs2.sh` 自有图片 URL。'
        steam_image:
          type: string
          description: 可选的 Valve Economy/static 官方图片 URL；仅在精确变体来源已得到独立证明时提供。缺少该字段不会移除必需的自有 `image`。
    SchemaItem:
      type: object
      description: 一条目录记录，在顶层 `items` 映射中按 `market_hash_name` 键控。不适用于该饰品的字段会被省略。
      required:
        - market_hash_name
        - category
        - image
        - is_tradable
      properties:
        market_hash_name:
          type: string
          description: 规范的 Steam market hash name（与价格端点一致）。
        category:
          type: string
          description: 饰品类别（例如 `skin`、`sticker`、`container`、`agent`）。
        image:
          type: string
          description: '`cs2.sh` 自有图片 URL。'
        steam_image:
          type: string
          description: 可选的 Valve Economy/static 官方图片 URL；仅在精确饰品来源已得到独立证明时提供。缺少该字段不会移除必需的自有 `image`。
        is_tradable:
          type: boolean
          description: 该饰品是否可交易。
        rarity:
          type: object
          description: 饰品稀有度：`name`、`tier` 和 `color`。
          required: [name, tier, color]
          properties:
            name:
              type: string
            tier:
              type: integer
            color:
              type: string
        collections:
          type: array
          description: 饰品所属的收藏品。没有时省略。
          items:
            type: string
        containers:
          type: array
          description: 掉落该饰品的容器。没有时省略。
          items:
            type: string
        ids:
          type: object
          description: 已知的市场目录 id。
          properties:
            buff:
              type: integer
            youpin:
              type: integer
            c5game:
              type: integer
        def_index:
          type: integer
          description: 饰品定义索引。
        base_name:
          type: string
          description: 不含外观后缀的基础饰品名称。仅限皮肤。
        weapon:
          type: string
          description: 武器名称。仅限皮肤。
        finish:
          type: string
          description: 涂装名称。仅限皮肤。
        paint_index:
          type: integer
          description: 涂装索引。仅限皮肤；Doppler 和 Gamma Doppler 基础饰品会省略。
        wears:
          type: array
          description: 该饰品存在的外观。仅限有外观分级的饰品。
          items:
            type: string
        has_stattrak:
          type: boolean
          description: 是否存在 StatTrak 版本。仅限有外观分级的饰品。
        has_souvenir:
          type: boolean
          description: 是否存在 Souvenir 版本。仅限有外观分级的饰品。
        float_range:
          type: object
          description: 该饰品的磨损上下界。仅限有外观分级的饰品。
          required: [min, max]
          properties:
            min:
              type: number
            max:
              type: number
        wear:
          type: string
          description: 该饰品的外观（例如 `Field-Tested`）。仅限有外观分级的饰品。
        wear_float_range:
          type: object
          description: 该外观行自身的磨损上下界，即 `float_range` 截取到该外观区间后的范围。仅限有外观分级的饰品。
          required: [min, max]
          properties:
            min:
              type: number
            max:
              type: number
        stattrak:
          type: boolean
          description: 该行是否为 StatTrak 版本。
        souvenir:
          type: boolean
          description: 该行是否为 Souvenir 版本。
        variants:
          type: array
          description: 该基础饰品的 Doppler / Gamma Doppler 相位或 Case Hardened 分层。
          items:
            $ref: '#/components/schemas/SchemaItemVariant'
        variant:
          type: object
          description: 变体行回链到其基础饰品。
          required: [family, name, of]
          properties:
            family:
              type: string
            name:
              type: string
            of:
              type: string
              description: 基础饰品 `market_hash_name`。
        phase:
          type: string
          description: 相位或宝石名称。仅限 Doppler 和 Gamma Doppler 变体行。
        color:
          type: string
          description: 十六进制强调色。仅限 Doppler 和 Gamma Doppler 变体行。
    SchemaResponse:
      type: object
      description: '`GET /v1/schema` 的响应结构：按 `market_hash_name` 键控的完整饰品目录及其元数据。'
      required:
        - schema_version
        - generation_id
        - generated_at
        - counts
        - rarities
        - collections
        - items
      properties:
        schema_version:
          type: string
          description: 目录 schema 版本。变化时客户端应重新同步。
        generation_id:
          type: string
          description: 此不可变 schema 代次的稳定标识符。
        generated_at:
          type: string
          format: date-time
          description: 此不可变 schema 代次的构建时间。比较 `generation_id` 可检测代次变化。
        counts:
          type: object
          description: 目录实体计数。
          required: [items, by_category, collections]
          properties:
            items:
              type: integer
              description: 饰品记录数量。
            by_category:
              type: object
              description: 每个类别的饰品数量。
              additionalProperties:
                type: integer
            collections:
              type: integer
              description: 收藏品数量。
        rarities:
          type: array
          description: 稀有度分层。
          items:
            $ref: '#/components/schemas/SchemaRarity'
        collections:
          type: object
          description: 按收藏品名称键控的收藏品元数据。
          additionalProperties:
            $ref: '#/components/schemas/SchemaCollection'
        items:
          type: object
          description: 按 `market_hash_name` 键控的饰品记录。
          additionalProperties:
            $ref: '#/components/schemas/SchemaItem'
      example:
        schema_version: v3
        generated_at: '2026-08-12T22:18:51Z'
        counts:
          items: 48696
          by_category:
            agent: 63
            collectible: 468
            container: 479
            graffiti: 2111
            highlight_reel: 926
            key: 39
            keychain: 78
            music_kit: 188
            patch: 112
            skin: 21924
            sticker: 11132
            sticker_slab: 11132
            tool: 4
            vanilla_skin: 40
          collections: 110
        rarities:
          - key: default
            name: Stock
            tier: 0
            color: '#b0c3d9'
          - key: common
            name: Consumer Grade
            tier: 1
            color: '#b0c3d9'
          - key: uncommon
            name: Industrial Grade
            tier: 2
            color: '#5e98d9'
          - key: rare
            name: Mil-Spec Grade
            tier: 3
            color: '#4b69ff'
          - key: mythical
            name: Restricted
            tier: 4
            color: '#8847ff'
          - key: legendary
            name: Classified
            tier: 5
            color: '#d32ce6'
          - key: ancient
            name: Covert
            tier: 6
            color: '#eb4b4b'
          - key: immortal
            name: Contraband
            tier: 7
            color: '#e4ae39'
        collections:
          2025 Community Sticker Collection:
            name: 2025 Community Sticker Collection
            kind: sticker
            release_date: '2025-10-01'
            released_at: '2025-10-01T23:42:32Z'
            update_name: Community Maps, Charms, and More
            announcement_url: https://steamcommunity.com/games/CSGO/announcements/detail/498333631688738073
            image: https://cs2.sh/image/5-y5BqjoeymuHNzv
            steam_image: https://cdn.steamstatic.com/apps/730/icons/econ/set_icons/set_community_2025.280d945244b90804541bf84784796793fd3bad00.png
          Auto Racing Sticker Collection:
            name: Auto Racing Sticker Collection
            kind: sticker
            release_date: '2026-07-08'
            released_at: '2026-07-08T22:50:43Z'
            update_name: Season 5, Armory, and More
            announcement_url: https://steamcommunity.com/games/CSGO/announcements/detail/701021228894257509
            image: https://cs2.sh/image/UuGTutGWjf5OvoVM
            steam_image: https://cdn.steamstatic.com/apps/730/icons/econ/set_icons/set_auto_racing.2bb35a9a9c95a4757596a2ebd2085c73529f184b.png
        items:
          USP-S | Printstream (Factory New):
            market_hash_name: USP-S | Printstream (Factory New)
            category: skin
            image: https://cs2.sh/image/N8Agkakkrq4y1Hm1
            steam_image: https://community.akamai.steamstatic.com/economy/image/i0CoZ81Ui0m-9KwlBY1L_18myuGuq1wfhWSaZgMttyVfPaERSR0Wqmu7LAocGIGz3UqlXOLrxM-vMGmW8VNxu5Dx60noTyLkjYbf7itX6vytbbZSI-WsG3SA_v5kue99XD2hkBwqjDGMnYftb3yUPFR0XsNyRrNc5kO5ltziMenr5lONj4kXyi2riywc7y9o5LtQAqQ7uvqAkScWnv4
            is_tradable: true
            rarity:
              name: Covert
              tier: 6
              color: '#eb4b4b'
            collections:
              - The Recoil Collection
            containers:
              - Recoil Case
            ids:
              buff: 900565
              youpin: 102375
              c5game: 1017617021485346800
            def_index: 61
            base_name: USP-S | Printstream
            weapon: USP-S
            finish: Printstream
            wears:
              - Factory New
              - Minimal Wear
              - Field-Tested
              - Well-Worn
              - Battle-Scarred
            has_stattrak: true
            has_souvenir: true
            float_range:
              min: 0
              max: 0.85
            paint_index: 1142
            wear: Factory New
            wear_float_range:
              min: 0
              max: 0.07
            stattrak: false
            souvenir: false
          ★ Karambit | Doppler (Factory New):
            market_hash_name: ★ Karambit | Doppler (Factory New)
            category: skin
            image: https://cs2.sh/image/vJQM7YiSwMZS1GsE
            steam_image: https://community.akamai.steamstatic.com/economy/image/i0CoZ81Ui0m-9KwlBY1L_18myuGuq1wfhWSaZgMttyVfPaERSR0Wqmu7LAocGIGz3UqlXOLrxM-vMGmW8VNxu5Dx60noTyL6kJ_m-B1Q7uCvZaZkNM-SA1iSze91u_FsTju_qhAmoT-Jn4bjJC_4Ml93UtZuRLQPsBawkNfiMbnl5AKMiopCnin7iCJBv31j4rkBBKEg-6zUjV3GY6p9v8dpLWT3Fg
            is_tradable: true
            rarity:
              name: Covert
              tier: 6
              color: '#eb4b4b'
            containers:
              - Chroma Case
              - Chroma 2 Case
              - Chroma 3 Case
            ids:
              buff: 42998
              youpin: 1785
              c5game: 22702
            def_index: 507
            base_name: ★ Karambit | Doppler
            weapon: Karambit
            finish: Doppler
            wears:
              - Factory New
              - Minimal Wear
            has_stattrak: true
            has_souvenir: false
            float_range:
              min: 0
              max: 0.08
            wear: Factory New
            wear_float_range:
              min: 0
              max: 0.07
            stattrak: false
            souvenir: false
            variants:
              - market_hash_name: ★ Karambit | Doppler (Factory New) | Phase 1
                family: doppler
                name: Phase 1
                image: https://cs2.sh/image/f7tv2IWIqPDquMsV
                steam_image: https://community.akamai.steamstatic.com/economy/image/i0CoZ81Ui0m-9KwlBY1L_18myuGuq1wfhWSaZgMttyVfPaERSR0Wqmu7LAocGIGz3UqlXOLrxM-vMGmW8VNxu5Dx60noTyL6kJ_m-B1Q7uCvZaZkNM-SA1iUzv5mvOR7cDm7lA4i4gKJk4jxNWXFb1cpDJR2FOFbsBTql9bjYbzq7gPZiN1MxH7_2ytNuCdpte1UB_Ui5OSJ2GbkVqni
                phase: Phase 1
                color: '#6e1b3a'
                paint_index: 418
        generation_id: '7645176062026597595'
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: 错误代码（例如 validation_error、unauthorized、rate_limited）
        message:
          type: string
          description: 人类可读错误消息
        request_id:
          type: string
          format: uuid
          description: 用于支持的唯一请求标识符
        details:
          type: object
          description: 额外错误详情（结构因错误类型而异）
  responses:
    ValidationError:
      description: 请求参数无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: validation_error
            message: items and start fields are required
            request_id: 550e8400-e29b-41d4-a716-446655440000
            details:
              missing:
                - items
                - start
    Unauthorized:
      description: API 密钥缺失或无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: unauthorized
            message: missing or invalid api key
            request_id: 550e8400-e29b-41d4-a716-446655440000
    RateLimited:
      description: 请求过多：超出每秒请求速率限制
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: rate_limited
            message: Too many requests. Please retry after a short backoff.
            request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: 请求的端点不在你的套餐范围内。Demo 和 Developer 密钥仅限访问最新数据端点和 `GET /v1/schema`；升级到 Scale 可获得完整访问权限。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: forbidden
            message: Your plan only has access to latest endpoints. Upgrade to Scale for full API access.
            request_id: 550e8400-e29b-41d4-a716-446655440000
    ServiceUnavailable:
      description: 服务暂时不可用
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: service_unavailable
            message: cache unavailable
            request_id: 550e8400-e29b-41d4-a716-446655440000
    GatewayTimeout:
      description: 请求超时
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: timeout
            message: query timeout
            request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: 饰品未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: not_found
            message: item not in liquidity cache
            request_id: 550e8400-e29b-41d4-a716-446655440000
            details:
              item: Invalid Item Name