openapi: 3.1.0
info:
  title: cs2.sh API Documentation
  version: 1.0.0
  description: |-
    REST API for Counter-Strike 2 item prices. All `/v1` requests require:

    - `Authorization: Bearer <api_key>` - your API key from the dashboard.
    - `Accept-Encoding: gzip` - successful 2xx responses are gzipped. Error responses are uncompressed even on `/v1` paths.

    **Plan gating.** Demo and Developer plans can call `GET/POST /v1/prices/latest`, `GET /v1/market/buff/latest`, `GET /v1/market/steam/latest`, and `GET /v1/schema`; other endpoints return `403 forbidden`. Scale and Enterprise plans have full access.

    **Body limits.** POST endpoints accept up to 100 items per request (max body 1 MiB). Unknown JSON fields are rejected. Values are trimmed and deduped before counting against the cap.

    **Items.** Items are identified by Steam `market_hash_name` (e.g. `USP-S | Printstream (Factory New)`).

    **Variants.** General price, history, archive, liquidity, and BUFF market endpoints can include a `variants` object for Doppler / Gamma Doppler phases or Case Hardened tiers. Dedicated Steam orderbook and native Steam market-history endpoints do not support variants and do not return a `variants` object.

    **Currency.** All prices are USD.
servers:
  - url: https://api.cs2.sh
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Service health monitoring
  - name: Prices
    description: Current and historical price data
  - name: Liquidity
    description: Liquidity ranking endpoints
  - name: BUFF Market
    description: BUFF market float/fade bucket endpoints
  - name: Steam Market
    description: Dedicated Steam Community Market orderbook and native sale-history endpoints
  - name: Archive
    description: Historical archive data with multi-year coverage
  - name: Schema
    description: Full item schema metadata
paths:
  /v1/prices/latest:
    get:
      operationId: getLatestPrices
      summary: Get all latest prices
      description: |
        Returns current prices for all items from all supported marketplaces. Includes variant prices.

        **Sources and available fields:**
        - `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

        Items with special patterns (Doppler phases, Case Hardened tiers) include a `variants` object. Variant `youpin` objects carry ask, bid, and bid_volume on every Doppler and Gamma Doppler phase, with ask_volume on most items.
      tags:
        - Prices
      responses:
        '200':
          description: Current prices for all items
          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: Get latest prices for specific items
      description: Returns current prices for up to 100 specific items.
      tags:
        - Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  description: List of market_hash_name values (max 100)
                  example:
                    - USP-S | Printstream (Factory New)
                    - ★ Karambit | Doppler (Factory New)
      responses:
        '200':
          description: Current prices for requested items
          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: Get historical OHLC prices
      description: |
        Returns continuously updated OHLC (Open/High/Low/Close) price history.

        **Coverage:** Data begins on December 24, 2025.

        **Recommended for:** Short-term price history.

        **Intervals and max ranges:**
        - `5m`: 14 days
        - `30m`: 90 days
        - `1h`: 365 days
        - `1d`: unlimited
      tags:
        - Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
                - start
              properties:
                items:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  description: List of market_hash_name values (max 100)
                  example:
                    - USP-S | Printstream (Factory New)
                start:
                  type: string
                  description: Start date (YYYY-MM-DD or RFC3339)
                  example: '2026-07-20'
                end:
                  type: string
                  description: 'End date (YYYY-MM-DD or RFC3339). Default: now'
                  example: '2026-07-23'
                sources:
                  type: array
                  items:
                    type: string
                    enum:
                      - buff
                      - youpin
                      - csfloat
                      - skinport
                      - steam
                      - c5game
                  description: 'Filter to specific sources. Default: all sources'
                  example:
                    - buff
                    - csfloat
                interval:
                  type: string
                  enum:
                    - 5m
                    - 30m
                    - 1h
                    - 1d
                  default: 5m
                  description: Aggregation interval
                  example: 1h
      responses:
        '200':
          description: Historical OHLC data
          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: Get item liquidity buckets
      description: |
        Returns the latest daily liquidity bucket and estimated sale time for all items.
      tags:
        - Liquidity
      responses:
        '200':
          description: Item liquidity for all items
          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: Get historical archive prices
      description: |
        Returns historical price data per platform from the long-term archive.

        **Response fields:** ask, bid, ask_volume, bid_volume per source. The `aggregate` source also includes `hourly_volume` and `total_supply`.

        **Intervals:**
        - `1h`: Hourly buckets
        - `1d`: Daily buckets (default)

        **Sources:** aggregate (all combined), buff, youpin, c5game

        **Coverage:** Data from 2023 onward.

        **Recommended for:** Long-term price history, total supply, and sale volume.

        **Update frequency:** Archive endpoints update ~1-2x per day.

        **Max items per request:** 100
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveHistoryRequest'
      responses:
        '200':
          description: Archive history data
          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: Get CSFloat historical sales
      description: |
        Returns historical sale data from CSFloat on a per-day basis.

        **Response fields:**
        - `volume`: Number of items sold that day
        - `price`: Arithmetic average of all sales that day

        **Coverage:** Data from 2022 onward.

        **Update frequency:** Archive endpoints update ~1-2x per day.

        **Max items per request:** 100
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveCSFloatRequest'
      responses:
        '200':
          description: CSFloat archive data
          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: Get native Steam archive buckets
      description: |
        Returns native Steam Community Market sale-history buckets. `price` is Steam's median sale price for the bucket and `volume` is the Steam purchases count.

        Buckets are Steam's native sale-history buckets in USD. Intervals are `1h` and `1d`, both unlimited in range.

        Variants are not supported. POST routes accept at most 100 items. Available on Scale and Enterprise plans only.
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveSteamRequest'
      responses:
        '200':
          description: Native Steam archive buckets grouped by item
          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: Get Youpin sale history
      description: |
        Returns Youpin sale prices at 1h / 4h / 12h intervals. Youpin publishes one sale per sampling bucket - this means that, if an item has multiple sales within the period, only the most recent will be used. Prices are USD, converted from CNY at each sale date's own historical rate.

        **Per-interval series:** Each item carries one independent series per width under `intervals`, keyed `1h`, `4h`, and `12h`. A key is present only when that width was observed inside the requested window: `count: 0` with an empty `data` means observed with nothing sold, an absent key means not observed. The same sale can appear at more than one width, so never sum series.

        **Response fields:**
        - `bucket`: start of the sampling bucket
        - `time`: actual sale time inside the bucket
        - `price`: sale price (USD)
        - `count`: points in that one series, not a sale volume

        **Coverage:** `12h` data from November 12, 2025; `4h` from June 27, 2026; `1h` from July 20, 2026. Items at or above the `liquid` bucket on `/v1/liquidity/items` are collected, roughly 16,000, plus Doppler, Gamma Doppler, and Case Hardened variants.

        **Update frequency:** Updates ~1-2x per day.

        **Max items per request:** 100
      tags:
        - Archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveYoupinRequest'
      responses:
        '200':
          description: Youpin sale history
          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: Get BUFF float and fade buckets for every item
      description: |
        Returns BUFF float and fade buckets for every item. Each item has one or more buckets identified by `bucket_type`: `base`, `float`, `fade`, or `float_fade`. Items with Doppler phases or Case Hardened tiers can include a `variants` object.

        BUFF refreshes float and fade buckets every 10 minutes.

        All prices are USD.

        Available on Demo, Developer, Scale, and Enterprise plans.
      tags:
        - BUFF Market
      responses:
        '200':
          description: BUFF market float/fade buckets for all items
          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: Get OHLC history for BUFF float and fade buckets
      description: |
        Returns OHLC history for BUFF float and fade buckets.

        **Coverage:** Data begins on May 19, 2026.

        **Intervals and max ranges:**
        - `30m`: 90 days
        - `1h`: 365 days
        - `1d`: unlimited

        Required fields: `items`, `start`. Optional `end` defaults to now. Optional `interval` defaults to `30m`.
      tags:
        - BUFF Market
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BUFFMarketFloatHistoryRequest'
      responses:
        '200':
          description: BUFF market float/fade OHLC history
          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: Get latest Steam full-depth orderbooks
      description: |
        Returns the latest full Steam bid/ask orderbook for all tracked regular items.

        Orderbook depth is columnar. `depth.asks.prices` is sorted ascending, `depth.bids.prices` is sorted descending, and each value in `volumes` corresponds to the price at the same array index. All prices are USD.

        Available on Demo, Developer, Scale, and Enterprise plans.
      tags:
        - Steam Market
      responses:
        '200':
          description: Latest full-depth Steam orderbooks for tracked regular items
          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: Get Steam orderbook bucket snapshots
      description: |
        Returns full-depth Steam orderbook snapshots over time. Each bucket contains the latest Steam observation collected inside that interval, with the same columnar depth shape as `GET /v1/market/steam/latest`.

        This is point-in-time depth, not OHLC; prices are not aggregated. Buckets are USD-only. Intervals are `1h` (90 days) and `1d` (unlimited).

        Variants are not supported. POST routes accept at most 100 items. Available on Scale and Enterprise plans only.
      tags:
        - Steam Market
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SteamOrderbookHistoryRequest'
      responses:
        '200':
          description: Steam orderbook snapshots grouped by item and bucket
          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: Get item schema
      description: |
        Returns a single schema containing all Counter-Strike 2 items. It's updated automatically when the game updates and contains ~47,500 items and ~110 collections keyed by `market_hash_name`, with rarities, wears and float ranges, marketplace ids, and item images. Variants are supported. Where applicable, items list their collections and containers.

        The full payload is large, so `Accept-Encoding: gzip` is required.

        Available on all plans.
      tags:
        - Schema
      responses:
        '200':
          description: Full item schema
          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: Service health status
      description: |
        Returns current source, variant, endpoint, schema, and aggregate health. No authentication required.

        A populated health response uses HTTP `200` even when `status` is `degraded` or `down`. HTTP `503` means health data is not ready.
      tags:
        - Health
      security: []
      responses:
        '200':
          description: Service health
          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: |
        API key issued for your cs2.sh account. Demo keys return `401 unauthorized`
        with `demo key expired` after their issued expiry timestamp; duration can differ by issuance channel.

        Demo and Developer plans are restricted to `GET/POST /v1/prices/latest`, `GET /v1/market/buff/latest`, `GET /v1/market/steam/latest`, and `GET /v1/schema`. Other endpoints return `403 forbidden`.
  schemas:
    HealthEntry:
      type: object
      description: Freshness and status for one source, variant collector, or endpoint dataset.
      required:
        - updated_at
        - collected_at
        - status
      properties:
        updated_at:
          type: string
          format: date-time
          description: Most recent source-data timestamp represented by this entry.
        collected_at:
          type: string
          format: date-time
          description: When cs2.sh most recently collected or produced this dataset.
        status:
          type: string
          enum:
            - up
            - degraded
            - down
          description: Health derived from the dataset's expected refresh rate.
    HealthStats:
      type: object
      description: Aggregate database counts at the last health refresh.
      required:
        - total_events
        - market_hash_names
        - variant_items
      properties:
        total_events:
          type: integer
          description: Total stored market-data events.
        market_hash_names:
          type: integer
          description: Unique item names represented in current market data.
        variant_items:
          type: integer
          description: Unique variant item names represented in current market data.
    HealthResponse:
      type: object
      description: Current health of cs2.sh data sources and public datasets.
      required:
        - status
        - last_refreshed_at
        - schema_ready
        - sources
        - variants
        - endpoints
        - stats
      properties:
        status:
          type: string
          enum:
            - up
            - degraded
            - down
          description: Overall API data health.
        last_refreshed_at:
          type: string
          format: date-time
          description: When this health snapshot was generated.
        schema_ready:
          type: boolean
          description: Whether the item schema is available.
        sources:
          type: object
          description: Marketplace health keyed by source.
          additionalProperties:
            $ref: '#/components/schemas/HealthEntry'
        variants:
          type: object
          description: Variant-price health keyed by source collector.
          additionalProperties:
            $ref: '#/components/schemas/HealthEntry'
        endpoints:
          type: object
          description: Dataset health keyed by endpoint name.
          additionalProperties:
            $ref: '#/components/schemas/HealthEntry'
        stats:
          $ref: '#/components/schemas/HealthStats'
    SkinportPriceWindow:
      type: object
      description: Skinport-supplied rolling price window. Object is `null` when Skinport has no recent sales for the item.
      required: [price, max_price, mean_price, median_price, volume]
      properties:
        price:
          type: number
          description: Last sale price (USD) within the window
        max_price:
          type: number
          description: Highest sale price (USD) within the window
        mean_price:
          type: number
          description: Average sale price (USD) within the window
        median_price:
          type: number
          description: Median sale price (USD) within the window
        volume:
          type: integer
          description: Number of sales within the window
    BUFFSourceData:
      type: object
      description: Price data from BUFF.
      required: [updated_at, collected_at, ask, ask_volume, bid, bid_volume]
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: When BUFF last updated this price
        collected_at:
          type: [string, "null"]
          format: date-time
          description: When cs2.sh fetched this data
        ask:
          type: [number, "null"]
          description: Lowest ask price (USD)
        ask_volume:
          type: [integer, "null"]
          description: Number of items listed for sale
        bid:
          type: [number, "null"]
          description: Highest buy-order price (USD)
        bid_volume:
          type: [integer, "null"]
          description: Number of active buy orders
    YoupinSourceData:
      type: object
      description: Price data from Youpin898.
      required: [updated_at, collected_at, ask, ask_volume, bid, bid_volume]
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: When Youpin last updated this price
        collected_at:
          type: [string, "null"]
          format: date-time
          description: When cs2.sh fetched this data
        ask:
          type: [number, "null"]
          description: Lowest ask price (USD)
        ask_volume:
          type: [integer, "null"]
          description: Number of items listed for sale
        bid:
          type: [number, "null"]
          description: Highest buy-order price (USD)
        bid_volume:
          type: [integer, "null"]
          description: Number of active buy orders
    CsfloatSourceData:
      type: object
      description: Current CSFloat listing and buy-order prices.
      required: [updated_at, collected_at, ask, ask_volume, bid]
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: When CSFloat last updated this price
        collected_at:
          type: [string, "null"]
          format: date-time
          description: When cs2.sh fetched this data
        ask:
          type: [number, "null"]
          description: Lowest ask price (USD)
        ask_volume:
          type: [integer, "null"]
          description: Number of items listed for sale
        bid:
          type: [number, "null"]
          description: Highest buy-order price (USD)
    SkinportSourceData:
      type: object
      description: Price data from Skinport, including Skinport-supplied rolling history windows.
      required: [updated_at, collected_at, ask, ask_volume, max_ask, mean_ask, median_ask, 24h_history, 7d_history, 30d_history, 90d_history]
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: When Skinport last updated this price
        collected_at:
          type: [string, "null"]
          format: date-time
          description: When cs2.sh fetched this data
        ask:
          type: [number, "null"]
          description: Lowest ask price (USD)
        ask_volume:
          type: [integer, "null"]
          description: Number of items listed for sale
        max_ask:
          type: [number, "null"]
          description: Highest listing price (USD)
        mean_ask:
          type: [number, "null"]
          description: Average listing price (USD)
        median_ask:
          type: [number, "null"]
          description: Median listing price (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
      description: Price data from the Steam Community Market.
      required: [updated_at, collected_at, ask, ask_volume, bid, bid_volume]
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: When the upstream price was last updated
        collected_at:
          type: [string, "null"]
          format: date-time
          description: When cs2.sh fetched this data
        ask:
          type: [number, "null"]
          description: Lowest ask price (USD)
        ask_volume:
          type: [integer, "null"]
          description: Number of items listed for sale
        bid:
          type: [number, "null"]
          description: Highest buy-order price (USD)
        bid_volume:
          type: [integer, "null"]
          description: Number of active buy orders
    C5GameSourceData:
      type: object
      description: Price data from C5Game. Ask and bid come from independent collection passes, so timestamps may differ for the same item.
      required: [updated_at, collected_at, ask, ask_volume, bid]
      properties:
        updated_at:
          type: [string, "null"]
          format: date-time
          description: When C5Game last updated this price
        collected_at:
          type: [string, "null"]
          format: date-time
          description: When cs2.sh fetched this data
        ask:
          type: [number, "null"]
          description: Lowest ask price (USD)
        ask_volume:
          type: [integer, "null"]
          description: Number of items listed for sale
        bid:
          type: [number, "null"]
          description: Highest buy-order price (USD)
    Variant:
      type: object
      description: A variant of an item (Doppler / Gamma Doppler phase or Case Hardened tier). `youpin` includes `ask`, `bid`, and `bid_volume` on every Doppler and Gamma Doppler phase, with `ask_volume` on most items.
      required: [market_hash_name, name, display_name, version]
      properties:
        market_hash_name:
          type: string
          description: 'Base item `market_hash_name`. Full variant name: `name`.'
        name:
          type: string
          description: The variant's full `market_hash_name`, e.g. `★ Karambit | Doppler (Factory New) | Phase 1`.
        display_name:
          type: string
          description: Human-readable variant label (e.g. `Phase 1`, `Ruby`, `Tier 1`, `Blue Gem`).
        version:
          type: string
          description: Stable variant code. Switch on this in client code.
          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
      description: Price data for an item across all sources.
      required: [market_hash_name, buff, youpin, csfloat, skinport, c5game, steam]
      properties:
        market_hash_name:
          type: string
          description: Steam market hash name (the canonical item identifier).
        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: Per-variant price data for items with Doppler / Gamma Doppler phases or Case Hardened tiers. Keyed by display name.
          additionalProperties:
            $ref: '#/components/schemas/Variant'
    LatestPricesGetResponse:
      type: object
      description: All-items snapshot. Returned by `GET /v1/prices/latest` with shared response metadata.
      required: [response_time, currency, items]
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated
        currency:
          type: string
          description: Currency code (always `USD`)
        items:
          type: object
          description: Map of `market_hash_name` to item price data.
          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
      description: Filtered per-item snapshot. Returned by `POST /v1/prices/latest` and includes per-item `errors`.
      required: [response_time, currency, items]
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated
        currency:
          type: string
          description: Currency code (always `USD`)
        items:
          type: object
          description: Map of `market_hash_name` to item price data, filtered to the requested items.
          additionalProperties:
            $ref: '#/components/schemas/Item'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: OHLC bucket of BUFF prices.
      properties:
        open_ask:
          type: [number, "null"]
          description: First ask price in the bucket
        high_ask:
          type: [number, "null"]
          description: Highest ask price in the bucket
        low_ask:
          type: [number, "null"]
          description: Lowest ask price in the bucket
        close_ask:
          type: [number, "null"]
          description: Last ask price in the bucket
        ask_volume:
          type: [integer, "null"]
          description: Last observed ask volume in the bucket
        open_bid:
          type: [number, "null"]
          description: First bid price in the bucket
        high_bid:
          type: [number, "null"]
          description: Highest bid price in the bucket
        low_bid:
          type: [number, "null"]
          description: Lowest bid price in the bucket
        close_bid:
          type: [number, "null"]
          description: Last bid price in the bucket
        bid_volume:
          type: [integer, "null"]
          description: Last observed bid volume in the bucket
        sample_count:
          type: integer
          description: Number of underlying 5-minute observations aggregated into this bucket
        open_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the first observation inside this bucket. Distinct from `bucket` (the interval boundary).
        close_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last observation inside this bucket. Distinct from `bucket` (the interval boundary).
    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: OHLC bucket of Youpin prices.
      properties:
        open_ask:
          type: [number, "null"]
          description: First ask price in the bucket
        high_ask:
          type: [number, "null"]
          description: Highest ask price in the bucket
        low_ask:
          type: [number, "null"]
          description: Lowest ask price in the bucket
        close_ask:
          type: [number, "null"]
          description: Last ask price in the bucket
        ask_volume:
          type: [integer, "null"]
          description: Last observed ask volume in the bucket
        open_bid:
          type: [number, "null"]
          description: First bid price in the bucket
        high_bid:
          type: [number, "null"]
          description: Highest bid price in the bucket
        low_bid:
          type: [number, "null"]
          description: Lowest bid price in the bucket
        close_bid:
          type: [number, "null"]
          description: Last bid price in the bucket
        bid_volume:
          type: [integer, "null"]
          description: Last observed bid volume in the bucket
        sample_count:
          type: integer
          description: Number of underlying 5-minute observations aggregated into this bucket
        open_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the first observation inside this bucket. Distinct from `bucket` (the interval boundary).
        close_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last observation inside this bucket. Distinct from `bucket` (the interval boundary).
    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: OHLC bucket of CSFloat ask and bid prices.
      properties:
        open_ask:
          type: [number, "null"]
          description: First ask price in the bucket
        high_ask:
          type: [number, "null"]
          description: Highest ask price in the bucket
        low_ask:
          type: [number, "null"]
          description: Lowest ask price in the bucket
        close_ask:
          type: [number, "null"]
          description: Last ask price in the bucket
        ask_volume:
          type: [integer, "null"]
          description: Last observed ask volume in the bucket
        open_bid:
          type: [number, "null"]
          description: First bid price in the bucket
        high_bid:
          type: [number, "null"]
          description: Highest bid price in the bucket
        low_bid:
          type: [number, "null"]
          description: Lowest bid price in the bucket
        close_bid:
          type: [number, "null"]
          description: Last bid price in the bucket
        sample_count:
          type: integer
          description: Number of underlying 5-minute observations aggregated into this bucket
        open_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the first observation inside this bucket. Distinct from `bucket` (the interval boundary).
        close_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last observation inside this bucket. Distinct from `bucket` (the interval boundary).
    SkinportOHLCSourceData:
      type: object
      required: [open_ask, high_ask, low_ask, close_ask, ask_volume, sample_count, open_time, close_time]
      description: OHLC bucket of Skinport ask prices.
      properties:
        open_ask:
          type: [number, "null"]
          description: First ask price in the bucket
        high_ask:
          type: [number, "null"]
          description: Highest ask price in the bucket
        low_ask:
          type: [number, "null"]
          description: Lowest ask price in the bucket
        close_ask:
          type: [number, "null"]
          description: Last ask price in the bucket
        ask_volume:
          type: [integer, "null"]
          description: Last observed ask volume in the bucket
        sample_count:
          type: integer
          description: Number of underlying 5-minute observations aggregated into this bucket
        open_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the first observation inside this bucket. Distinct from `bucket` (the interval boundary).
        close_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last observation inside this bucket. Distinct from `bucket` (the interval boundary).
    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: OHLC bucket of Steam Community Market ask and bid prices.
      properties:
        open_ask:
          type: [number, "null"]
          description: First ask price in the bucket
        high_ask:
          type: [number, "null"]
          description: Highest ask price in the bucket
        low_ask:
          type: [number, "null"]
          description: Lowest ask price in the bucket
        close_ask:
          type: [number, "null"]
          description: Last ask price in the bucket
        ask_volume:
          type: [integer, "null"]
          description: Last observed ask volume in the bucket
        open_bid:
          type: [number, "null"]
          description: First bid price in the bucket
        high_bid:
          type: [number, "null"]
          description: Highest bid price in the bucket
        low_bid:
          type: [number, "null"]
          description: Lowest bid price in the bucket
        close_bid:
          type: [number, "null"]
          description: Last bid price in the bucket
        bid_volume:
          type: [integer, "null"]
          description: Last observed bid volume in the bucket
        sample_count:
          type: integer
          description: Number of underlying 5-minute observations aggregated into this bucket
        open_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the first observation inside this bucket. Distinct from `bucket` (the interval boundary).
        close_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last observation inside this bucket. Distinct from `bucket` (the interval boundary).
    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: OHLC bucket of C5Game ask and bid prices.
      properties:
        open_ask:
          type: [number, "null"]
          description: First ask price in the bucket
        high_ask:
          type: [number, "null"]
          description: Highest ask price in the bucket
        low_ask:
          type: [number, "null"]
          description: Lowest ask price in the bucket
        close_ask:
          type: [number, "null"]
          description: Last ask price in the bucket
        ask_volume:
          type: [integer, "null"]
          description: Last observed ask volume in the bucket
        open_bid:
          type: [number, "null"]
          description: First bid price in the bucket
        high_bid:
          type: [number, "null"]
          description: Highest bid price in the bucket
        low_bid:
          type: [number, "null"]
          description: Lowest bid price in the bucket
        close_bid:
          type: [number, "null"]
          description: Last bid price in the bucket
        sample_count:
          type: integer
          description: Number of underlying 5-minute observations aggregated into this bucket
        open_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the first observation inside this bucket. Distinct from `bucket` (the interval boundary).
        close_time:
          type: [string, "null"]
          format: date-time
          description: Timestamp of the last observation inside this bucket. Distinct from `bucket` (the interval boundary).
    HistoryBucket:
      type: object
      required: [bucket]
      description: A single OHLC time bucket. `bucket` is the interval boundary (UTC-aligned, deterministic); `open_time`/`close_time` on each per-source object are the actual first/last observation timestamps inside it.
      properties:
        bucket:
          type: string
          format: date-time
          description: Start of the time bucket. UTC-aligned to the interval boundary (e.g. `2026-01-08T19:00:00Z` for an `1h` bucket). Deterministic.
        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 time-series for a single item.
      properties:
        market_hash_name:
          type: string
          description: Steam market hash name (the canonical item identifier).
        count:
          type: integer
          description: Number of buckets with data
        data:
          type: array
          description: OHLC buckets in chronological order.
          items:
            $ref: '#/components/schemas/HistoryBucket'
        variants:
          type: object
          description: Per-variant OHLC time-series for items with Doppler / Gamma Doppler phases or Case Hardened tiers. Keyed by display name.
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, count, data]
            properties:
              market_hash_name:
                type: string
                description: The base item's `market_hash_name`.
              name:
                type: string
                description: The variant's full `market_hash_name`.
              display_name:
                type: string
                description: Human-readable variant label.
              version:
                type: string
                description: Stable variant code.
              count:
                type: integer
                description: Number of buckets with data for this variant.
              data:
                type: array
                description: OHLC buckets in chronological order.
                items:
                  $ref: '#/components/schemas/HistoryBucket'
    HistoryResponse:
      type: object
      required: [response_time, currency, start, end, interval, items]
      description: Response shape for `POST /v1/prices/history`.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Effective start of the queried range, floored to the interval boundary.
        end:
          type: string
          format: date-time
          description: Effective end of the queried range, ceiled to the interval boundary. Exclusive.
        interval:
          type: string
          enum:
            - 5m
            - 30m
            - 1h
            - 1d
          description: OHLC bucket size.
        items:
          type: object
          description: Map of `market_hash_name` to OHLC time-series.
          additionalProperties:
            $ref: '#/components/schemas/HistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: Item liquidity bucket and estimated sale time for a single item.
      properties:
        market_hash_name:
          type: string
          description: Steam market hash name.
        liquidity:
          type: string
          enum: [unknown, extremely_illiquid, very_illiquid, illiquid, moderate, liquid, very_liquid, extremely_liquid]
          description: Recomputed item liquidity bucket.
        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: 80th-percentile estimated time for a competitively priced listing to sell.
        variants:
          type: object
          description: Per-variant item liquidity keyed by display name.
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, liquidity, estimated_sale_time]
            properties:
              market_hash_name:
                type: string
                description: The base item's `market_hash_name`.
              name:
                type: string
                description: The variant's full `market_hash_name`.
              display_name:
                type: string
                description: Human-readable variant label.
              version:
                type: string
                description: Stable variant code.
              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: All-items liquidity snapshot. Returned by `GET /v1/liquidity/items`.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the snapshot was computed.
        run_date:
          type: string
          format: date
          description: UTC date for the daily computation.
        items:
          type: object
          description: Map of `market_hash_name` to item liquidity data.
          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: Numeric range for a `float` or `fade` bucket. `min` is inclusive, `max` is exclusive.
      properties:
        min:
          type: number
          description: Inclusive lower bound.
        max:
          type: number
          description: Exclusive upper bound.
    BUFFMarketFloatLatestBucket:
      type: object
      required: [bucket_id, bucket_type]
      description: One latest BUFF float or fade range bucket, identified by `bucket_type`.
      properties:
        bucket_id:
          type: string
          description: Stable bucket identifier (e.g. `base`, `float:0.15:0.18`, `variant:p2|float:0.00:0.01`).
        bucket_type:
          type: string
          enum:
            - base
            - float
            - fade
            - float_fade
          description: |
            Bucket stratification.
            - `base`: aggregated across the entire item or variant.
            - `float`: float-range slice (see `float`).
            - `fade`: fade-percentage slice (see `fade`).
            - `float_fade`: combined float and fade slice.
        float:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        fade:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        updated_at:
          type: string
          format: date-time
          description: When BUFF last refreshed this bucket.
        collected_at:
          type: string
          format: date-time
          description: When cs2.sh fetched this bucket.
        ask:
          type: number
          description: Lowest ask price (USD) in this bucket.
        avg_ask:
          type: number
          description: Average ask price (USD) in the bucket.
        bid:
          type: number
          description: Highest buy-order price (USD) on BUFF.
        ask_volume:
          type: integer
          description: Number of items listed for sale in this bucket.
        bid_volume:
          type: integer
          description: Number of active buy orders against this bucket.
    BUFFMarketFloatHistoryPoint:
      type: object
      required: [bucket, open_time, close_time]
      description: A single OHLC observation inside a BUFF market float/fade bucket history.
      properties:
        bucket:
          type: string
          format: date-time
          description: UTC-aligned start of the OHLC interval.
        updated_at:
          type: string
          format: date-time
          description: When BUFF last refreshed the bucket inside this interval.
        collected_at:
          type: string
          format: date-time
          description: When cs2.sh fetched the source rows inside this interval.
        open_ask:
          type: number
          description: First ask price (USD) observed in the interval.
        high_ask:
          type: number
          description: Highest ask price (USD) observed in the interval.
        low_ask:
          type: number
          description: Lowest ask price (USD) observed in the interval.
        close_ask:
          type: number
          description: Last ask price (USD) observed in the interval.
        open_avg_ask:
          type: number
          description: First `avg_ask` value observed in the interval.
        high_avg_ask:
          type: number
          description: Highest `avg_ask` value observed in the interval.
        low_avg_ask:
          type: number
          description: Lowest `avg_ask` value observed in the interval.
        close_avg_ask:
          type: number
          description: Last `avg_ask` value observed in the interval.
        open_bid:
          type: number
          description: First bid price (USD) observed in the interval.
        high_bid:
          type: number
          description: Highest bid price (USD) observed in the interval.
        low_bid:
          type: number
          description: Lowest bid price (USD) observed in the interval.
        close_bid:
          type: number
          description: Last bid price (USD) observed in the interval.
        ask_volume:
          type: integer
          description: Last observed ask volume inside the interval.
        bid_volume:
          type: integer
          description: Last observed bid volume inside the interval.
        open_time:
          type: string
          format: date-time
          description: Timestamp of the first observation inside the interval. Distinct from `bucket` (the interval boundary).
        close_time:
          type: string
          format: date-time
          description: Timestamp of the last observation inside the interval. Distinct from `bucket` (the interval boundary).
    BUFFMarketFloatHistoryBucket:
      type: object
      required: [bucket_id, bucket_type, data]
      description: OHLC history for one BUFF market bucket. Each entry in `data` is one interval, in chronological order.
      properties:
        bucket_id:
          type: string
          description: Stable bucket identifier (e.g. `fade:99:100`, `variant:p2|float:0.00:0.01`).
        bucket_type:
          type: string
          enum:
            - base
            - float
            - fade
            - float_fade
          description: Bucket stratification. See `BUFFMarketFloatLatestBucket.bucket_type`.
        float:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        fade:
          $ref: '#/components/schemas/BUFFMarketFloatRange'
        data:
          type: array
          description: OHLC observations for this bucket, chronological.
          items:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryPoint'
    BUFFMarketFloatVariant:
      type: object
      required: [market_hash_name, name, display_name, version, buckets]
      description: BUFF latest data for a single variant of an item (Doppler / Gamma Doppler phase or Case Hardened tier).
      properties:
        market_hash_name:
          type: string
          description: Base item's `market_hash_name`. Full variant name lives in `name`.
        name:
          type: string
          description: The variant's full `market_hash_name`, e.g. `★ M9 Bayonet | Doppler (Factory New) | Phase 1`.
        display_name:
          type: string
          description: Human-readable variant label (e.g. `Phase 1`, `Ruby`, `Tier 1`).
        version:
          type: string
          description: Stable variant code. Switch on this in client code.
        buckets:
          type: array
          description: Latest BUFF buckets for this variant.
          items:
            $ref: '#/components/schemas/BUFFMarketFloatLatestBucket'
    BUFFMarketFloatHistoryVariant:
      type: object
      required: [market_hash_name, name, display_name, version, buckets]
      description: BUFF OHLC history for a single variant of an item.
      properties:
        market_hash_name:
          type: string
          description: Base item's `market_hash_name`. Full variant name lives in `name`.
        name:
          type: string
          description: The variant's full `market_hash_name`, e.g. `★ M9 Bayonet | Doppler (Factory New) | Phase 1`.
        display_name:
          type: string
          description: Human-readable variant label.
        version:
          type: string
          description: Stable variant code.
        buckets:
          type: array
          description: OHLC history per bucket for this variant.
          items:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryBucket'
    BUFFMarketFloatItem:
      type: object
      required: [market_hash_name]
      description: BUFF market float/fade data for one item.
      properties:
        market_hash_name:
          type: string
          description: Canonical base `market_hash_name`.
        buckets:
          type: array
          description: Latest BUFF buckets for the base listing.
          items:
            $ref: '#/components/schemas/BUFFMarketFloatLatestBucket'
        variants:
          type: object
          description: Per-variant BUFF data for items with Doppler / Gamma Doppler phases or Case Hardened tiers. Keyed by display name (e.g. `Phase 1`, `Ruby`, `Tier 1`).
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatVariant'
    BUFFMarketFloatHistoryItem:
      type: object
      required: [market_hash_name]
      description: BUFF market float/fade OHLC history for one item.
      properties:
        market_hash_name:
          type: string
          description: Canonical base `market_hash_name`.
        buckets:
          type: array
          description: OHLC history for the base listing's buckets.
          items:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryBucket'
        variants:
          type: object
          description: Per-variant OHLC history for items with Doppler / Gamma Doppler phases or Case Hardened tiers. Keyed by display name.
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryVariant'
    BUFFMarketFloatLatestResponse:
      type: object
      required: [response_time, currency, items]
      description: All-items BUFF float and fade range snapshot. Returned by `GET /v1/market/buff/latest`; all prices are USD.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        items:
          type: object
          description: Map of `market_hash_name` to per-item BUFF data.
          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: List of market_hash_name values (max 100)
          example:
            - ★ Bayonet | Fade (Factory New)
            - AK-47 | Case Hardened (Field-Tested)
        start:
          type: string
          description: Start date/time as YYYY-MM-DD or RFC3339
          example: '2026-07-20'
        end:
          type: string
          description: End date/time as YYYY-MM-DD or RFC3339. Defaults to now.
          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: Response shape for `POST /v1/market/buff/history`. Returns OHLC history for each requested BUFF market float/fade bucket.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Effective start of the queried range, floored to the interval boundary.
        end:
          type: string
          format: date-time
          description: Effective end of the queried range, ceiled to the interval boundary. Exclusive.
        interval:
          type: string
          enum:
            - 30m
            - 1h
            - 1d
          description: OHLC bucket size.
        items:
          type: object
          description: Map of `market_hash_name` to per-item BUFF history.
          additionalProperties:
            $ref: '#/components/schemas/BUFFMarketFloatHistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: Top-of-book best ask/bid for a Steam orderbook. Each field is `null` when that side is absent.
      required:
        - ask
        - ask_volume
        - bid
        - bid_volume
      properties:
        ask:
          type: [number, "null"]
          description: Best sell price in USD, or `null` when absent.
        ask_volume:
          type: [integer, "null"]
          description: Total Steam sell-order count, or `null` when absent.
        bid:
          type: [number, "null"]
          description: Best buy-order price in USD, or `null` when absent.
        bid_volume:
          type: [integer, "null"]
          description: Total Steam buy-order count, or `null` when absent.
    SteamOrderbookDepthSide:
      type: object
      description: One side of the orderbook ladder in columnar form. `prices[i]` pairs with `volumes[i]`; each `volume` is the quantity available at that exact price, not cumulative.
      required:
        - prices
        - volumes
      properties:
        prices:
          type: array
          description: Decimal USD prices. Asks ascending, bids descending.
          items:
            type: number
        volumes:
          type: array
          description: Quantity available at each corresponding price.
          items:
            type: integer
    SteamOrderbookDepth:
      type: object
      description: Full-depth Steam orderbook ladders in columnar form.
      required:
        - ask_levels
        - bid_levels
        - asks
        - bids
      properties:
        ask_levels:
          type: integer
          description: Number of ask levels in `asks`.
        bid_levels:
          type: integer
          description: Number of bid levels in `bids`.
        asks:
          $ref: '#/components/schemas/SteamOrderbookDepthSide'
        bids:
          $ref: '#/components/schemas/SteamOrderbookDepthSide'
    SteamOrderbookItem:
      type: object
      description: Latest full-depth Steam orderbook for one regular item.
      required:
        - updated_at
        - collected_at
        - top
        - depth
      properties:
        updated_at:
          type: string
          format: date-time
          description: When Steam last updated this orderbook.
        collected_at:
          type: string
          format: date-time
          description: When cs2.sh collected this orderbook.
        top:
          $ref: '#/components/schemas/SteamOrderbookTop'
        depth:
          $ref: '#/components/schemas/SteamOrderbookDepth'
    SteamOrderbookLatestResponse:
      type: object
      description: Latest Steam orderbook snapshot for all tracked regular items. Returned by `GET /v1/market/steam/latest`; variants are not supported.
      required:
        - response_time
        - currency
        - as_of
        - items
      properties:
        response_time:
          type: string
          format: date-time
          description: When this snapshot response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        as_of:
          type: string
          format: date-time
          description: Latest `updated_at` represented anywhere in the snapshot.
        items:
          type: object
          description: Regular items with current orderbook data, keyed by `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: List of regular `market_hash_name` values (max 100). Variants are not supported.
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: Start date/time as YYYY-MM-DD or RFC3339, inclusive.
          example: '2026-07-20'
        end:
          type: string
          description: End date/time as YYYY-MM-DD or RFC3339, exclusive. Defaults to now.
          example: '2026-07-23'
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: Bucket interval. `1h` is limited to 90 days; `1d` is unlimited.
          example: 1h
    SteamOrderbookHistoryPoint:
      type: object
      description: One latest-in-bucket full-depth Steam orderbook snapshot. This is not OHLC data.
      required:
        - bucket
        - updated_at
        - collected_at
        - top
        - depth
      properties:
        bucket:
          type: string
          format: date-time
          description: UTC bucket start.
        updated_at:
          type: string
          format: date-time
          description: When Steam last updated the orderbook represented by this bucket.
        collected_at:
          type: string
          format: date-time
          description: When cs2.sh collected the orderbook represented by this bucket.
        top:
          $ref: '#/components/schemas/SteamOrderbookTop'
        depth:
          $ref: '#/components/schemas/SteamOrderbookDepth'
    SteamOrderbookHistoryItem:
      type: object
      description: Steam orderbook bucket snapshots for one regular item. No variants are returned.
      required:
        - count
        - data
      properties:
        count:
          type: integer
          description: Number of points in `data`.
        data:
          type: array
          description: Points sorted ascending by `bucket`.
          items:
            $ref: '#/components/schemas/SteamOrderbookHistoryPoint'
    SteamOrderbookHistoryResponse:
      type: object
      description: Response shape for `POST /v1/market/steam/history`. Valid regular items with no rows are omitted; if all valid regular items have no rows, `items` is empty.
      required:
        - response_time
        - currency
        - start
        - end
        - interval
        - items
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Normalized UTC inclusive start.
        end:
          type: string
          format: date-time
          description: Normalized UTC exclusive end.
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: Requested bucket interval.
        items:
          type: object
          description: Map of `market_hash_name` to returned orderbook history.
          additionalProperties:
            $ref: '#/components/schemas/SteamOrderbookHistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: List of regular `market_hash_name` values (max 100). Variants are not supported.
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: Start date/time as YYYY-MM-DD or RFC3339, inclusive.
          example: '2025-01-01'
        end:
          type: string
          description: End date/time as YYYY-MM-DD or RFC3339, exclusive. Defaults to now.
          example: '2025-02-01'
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: Native Steam bucket interval. No public max date range.
          example: 1d
    ArchiveSteamBucket:
      type: object
      description: One native Steam sale-history bucket. `price` is Steam median sale price and `volume` is purchases.
      required:
        - bucket
        - price
        - volume
      properties:
        bucket:
          type: string
          format: date-time
          description: Native Steam bucket start.
        price:
          type: [number, "null"]
          description: Steam median sale price in USD.
        volume:
          type: [integer, "null"]
          description: Steam purchase count.
    ArchiveSteamItem:
      type: object
      description: Native Steam sale-history buckets for one regular item. No variants are returned.
      required:
        - market_hash_name
        - count
        - data
      properties:
        market_hash_name:
          type: string
          description: Canonical regular Steam market hash name.
        count:
          type: integer
          description: Number of buckets in `data`.
        data:
          type: array
          description: Buckets sorted ascending by `bucket`.
          items:
            $ref: '#/components/schemas/ArchiveSteamBucket'
    ArchiveSteamResponse:
      type: object
      description: Response shape for `POST /v1/archive/steam`. Valid regular items with no rows return item-level `not_in_archive`; if every valid regular item has no rows, the endpoint returns `404 not_found`.
      required:
        - response_time
        - currency
        - start
        - end
        - interval
        - items
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Normalized UTC inclusive start.
        end:
          type: string
          format: date-time
          description: Normalized UTC exclusive end.
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: Requested native Steam interval for every returned bucket.
        items:
          type: object
          description: Map of `market_hash_name` to native Steam sale-history buckets.
          additionalProperties:
            $ref: '#/components/schemas/ArchiveSteamItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: Error for a specific item in partial success response
      properties:
        item:
          type: string
          description: The requested item name that failed
        code:
          type: string
          enum:
            - unknown_item
            - not_in_cache
            - invalid_format
            - not_in_archive
            - unsupported_variant
            - unsupported_source
          description: Error code
        message:
          type: string
          description: Human-readable error message
    ArchiveCSFloatRequest:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
          maxItems: 100
          description: List of market_hash_name values (max 100)
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: Start date (YYYY-MM-DD or RFC3339). Default 2020-01-01.
          example: '2024-01-01'
        end:
          type: string
          description: End date (YYYY-MM-DD or RFC3339). Default now.
          example: '2026-07-26'
    ArchiveCSFloatBucket:
      type: object
      required: [date, price, volume]
      description: One day of sale data on CSFloat.
      properties:
        date:
          type: string
          description: Date in `YYYY-MM-DD` format (UTC).
        price:
          type: [number, "null"]
          description: Arithmetic average of all sale prices (USD) that day.
        volume:
          type: integer
          description: Number of sales that day.
    ArchiveCSFloatItem:
      type: object
      required: [market_hash_name, count, data]
      description: CSFloat sale time-series for a single item.
      properties:
        market_hash_name:
          type: string
          description: Steam market hash name.
        count:
          type: integer
          description: Number of days with data
        data:
          type: array
          description: Daily sale aggregates in chronological order.
          items:
            $ref: '#/components/schemas/ArchiveCSFloatBucket'
        variants:
          type: object
          description: Per-variant CSFloat sale time-series for items with Doppler / Gamma Doppler phases or Case Hardened tiers. Keyed by display name.
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, count, data]
            properties:
              market_hash_name:
                type: string
                description: The base item's `market_hash_name`.
              name:
                type: string
                description: The variant's full `market_hash_name`.
              display_name:
                type: string
                description: Human-readable variant label.
              version:
                type: string
                description: Stable variant code.
              count:
                type: integer
                description: Number of days with data for this variant.
              data:
                type: array
                description: Daily sale aggregates in chronological order.
                items:
                  $ref: '#/components/schemas/ArchiveCSFloatBucket'
    ArchiveCSFloatResponse:
      type: object
      required: [response_time, currency, start, end, items]
      description: Response shape for `POST /v1/archive/csfloat`.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Effective start of the queried range, floored to the day boundary.
        end:
          type: string
          format: date-time
          description: Effective end of the queried range, ceiled to the day boundary. Exclusive.
        items:
          type: object
          description: Map of `market_hash_name` to CSFloat sale time-series.
          additionalProperties:
            $ref: '#/components/schemas/ArchiveCSFloatItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: List of market_hash_name values (max 100)
          example:
            - ★ Karambit | Doppler (Factory New)
        start:
          type: string
          description: Start date (YYYY-MM-DD or RFC3339). Default 180 days ago. Floored to the hour.
          example: '2026-01-29'
        end:
          type: string
          description: End date (YYYY-MM-DD or RFC3339). Default now. Ceiled to the hour.
          example: '2026-07-28'
    ArchiveYoupinPoint:
      type: object
      required: [bucket, time, price]
      description: One sale on Youpin. Youpin keeps one sale per sampling bucket, so a point is a real sale, not an aggregate. The sampling interval is the series key, never a field on the point.
      properties:
        bucket:
          type: string
          format: date-time
          description: Start of the provider sampling bucket the point represents, at the width of the series holding it.
        time:
          type: string
          format: date-time
          description: Actual sale time inside the bucket.
        price:
          type: [number, "null"]
          description: Sale price (USD), converted from CNY at the sale date's own historical rate, or `null` when no rate for that date could be resolved.
    ArchiveYoupinSeries:
      type: object
      required: [count, data]
      description: One independent Youpin sale series at a single provider sampling interval, carrying exactly `count` and `data`. Series are never stitched, summed, or interleaved with one another.
      properties:
        count:
          type: integer
          description: Number of points in this series, equal to the length of `data`. This is not a sale volume, and `count` of 0 with an empty `data` means the interval was observed and no sales landed in the window.
        data:
          type: array
          description: Sales at this interval, ordered by bucket.
          items:
            $ref: '#/components/schemas/ArchiveYoupinPoint'
    ArchiveYoupinItem:
      type: object
      required: [market_hash_name, intervals]
      description: Youpin sale history for a single item, served as one independent series per provider sampling interval.
      properties:
        market_hash_name:
          type: string
          description: Steam market hash name.
        intervals:
          type: object
          description: Independent series keyed by provider sampling interval, emitted in `1h`, `4h`, `12h` order. A key is present only when that interval was observed inside the requested window, so an entry that exists only to carry requested variants returns `{}`.
          properties:
            1h:
              $ref: '#/components/schemas/ArchiveYoupinSeries'
            4h:
              $ref: '#/components/schemas/ArchiveYoupinSeries'
            12h:
              $ref: '#/components/schemas/ArchiveYoupinSeries'
        variants:
          type: object
          description: Per-variant Youpin sale history for items with Doppler or Gamma Doppler phases or Case Hardened tiers. Keyed by display name, and omitted when empty. A variant series never falls back to base history.
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, intervals]
            properties:
              market_hash_name:
                type: string
                description: The base item's `market_hash_name`.
              name:
                type: string
                description: The variant's full `market_hash_name`.
              display_name:
                type: string
                description: Human-readable variant label.
              version:
                type: string
                description: Stable variant code.
              intervals:
                type: object
                description: Independent series for this variant, keyed by provider sampling interval, under the same rules as the item's `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: Response shape for `POST /v1/archive/youpin`.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Effective start of the queried range, floored to the 1h boundary.
        end:
          type: string
          format: date-time
          description: Effective end of the queried range, ceiled to the 1h boundary. Exclusive.
        items:
          type: object
          description: Map of `market_hash_name` to Youpin sale series.
          additionalProperties:
            $ref: '#/components/schemas/ArchiveYoupinItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: List of market_hash_name values (max 100)
          example:
            - USP-S | Printstream (Factory New)
        start:
          type: string
          description: Start date (YYYY-MM-DD or RFC3339)
          example: '2024-01-01'
        end:
          type: string
          description: End date (YYYY-MM-DD or RFC3339). Default now.
          example: '2026-07-26'
        sources:
          type: array
          items:
            type: string
            enum:
              - aggregate
              - buff
              - youpin
              - c5game
          description: 'Filter to specific sources. Default: aggregate only.'
          example:
            - aggregate
            - buff
        interval:
          type: string
          enum:
            - 1h
            - 1d
          default: 1d
          description: Aggregation interval
          example: 1d
    ArchiveHistoryPlatformData:
      type: object
      required: [time, ask, ask_volume, bid, bid_volume, sample_count]
      description: Per-platform price data within an archive bucket. `hourly_volume` and `total_supply` are populated only on the `aggregate` platform.
      properties:
        time:
          type: string
          format: date-time
          description: Actual timestamp of the last observation in the bucket. Distinct from the bucket boundary.
        ask:
          type: [number, "null"]
          description: Last observed ask price (USD) in the bucket.
        ask_volume:
          type: [integer, "null"]
          description: Last observed number of items listed for sale.
        bid:
          type: [number, "null"]
          description: Last observed bid price (USD) in the bucket.
        bid_volume:
          type: [integer, "null"]
          description: Last observed number of buy orders.
        hourly_volume:
          type: [number, "null"]
          description: Aggregated trading volume metric (`aggregate` platform only).
        total_supply:
          type: [number, "null"]
          description: Total market supply metric (`aggregate` platform only).
        sample_count:
          type: integer
          description: Number of observations aggregated into this bucket.
    ArchiveHistoryBucket:
      type: object
      required: [bucket]
      description: A single archive time bucket. Each platform key is present only when data exists for that platform in this bucket.
      properties:
        bucket:
          type: string
          format: date-time
          description: Start of the time bucket (UTC-aligned to the interval boundary).
        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: Long-term archive time-series for a single item.
      properties:
        market_hash_name:
          type: string
          description: Steam market hash name.
        count:
          type: integer
          description: Number of buckets with data.
        data:
          type: array
          description: Archive buckets in chronological order.
          items:
            $ref: '#/components/schemas/ArchiveHistoryBucket'
        variants:
          type: object
          description: Per-variant archive time-series for items with Doppler / Gamma Doppler phases or Case Hardened tiers. Keyed by display name.
          additionalProperties:
            type: object
            required: [market_hash_name, name, display_name, version, count, data]
            properties:
              market_hash_name:
                type: string
                description: The base item's `market_hash_name`.
              name:
                type: string
                description: The variant's full `market_hash_name`.
              display_name:
                type: string
                description: Human-readable variant label.
              version:
                type: string
                description: Stable variant code.
              count:
                type: integer
                description: Number of buckets with data for this variant.
              data:
                type: array
                description: Archive buckets in chronological order.
                items:
                  $ref: '#/components/schemas/ArchiveHistoryBucket'
    ArchiveHistoryResponse:
      type: object
      required: [response_time, currency, start, end, interval, items]
      description: Response shape for `POST /v1/archive/history`.
      properties:
        response_time:
          type: string
          format: date-time
          description: When the response was generated.
        currency:
          type: string
          description: Currency code (always `USD`).
        start:
          type: string
          format: date-time
          description: Effective start of the queried range, floored to the interval boundary.
        end:
          type: string
          format: date-time
          description: Effective end of the queried range, ceiled to the interval boundary. Exclusive.
        interval:
          type: string
          enum:
            - 1h
            - 1d
          description: Archive bucket size.
        items:
          type: object
          description: Map of `market_hash_name` to archive time-series.
          additionalProperties:
            $ref: '#/components/schemas/ArchiveHistoryItem'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ItemError'
          description: Per-item failures alongside successful results (partial success).
      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: A rarity tier. Listed in the top-level `rarities` array and referenced by item-level `rarity`.
      required:
        - key
        - name
        - tier
        - color
      properties:
        key:
          type: string
          description: Stable rarity key (e.g. `ancient`, `legendary`).
        name:
          type: string
          description: Display name (e.g. `Covert`, `Classified`).
        tier:
          type: integer
          description: Numeric rarity tier, ascending with rarity.
        color:
          type: string
          description: Hex color for the rarity.
    SchemaCollection:
      type: object
      description: Collection metadata. Keyed by collection name in the top-level `collections` map.
      required:
        - name
        - kind
      properties:
        name:
          type: string
          description: Collection name.
        kind:
          type: string
          description: Collection kind (e.g. `weapon`, `sticker`).
        release_date:
          type: string
          description: Release date (`YYYY-MM-DD`), when known. An item's release date is its collection's; items carry `collections`, so join on that rather than expecting a date per item.
        released_at:
          type: string
          description: Exact publication instant of the Valve announcement that shipped the collection (RFC 3339 UTC). Present only where that announcement is known.
        update_name:
          type: string
          description: Valve's own name for that update, e.g. `Season 5, Armory, and More`.
        announcement_url:
          type: string
          description: Canonical Steam announcement for that update.
        image:
          type: string
          description: Owned image URL served from `cs2.sh`, when available.
        steam_image:
          type: string
          description: Optional official Valve Economy/static image URL, emitted only when the exact origin is independently proven.
    SchemaItemVariant:
      type: object
      description: A Doppler / Gamma Doppler phase or Case Hardened tier listed under a base item's `variants`.
      required:
        - market_hash_name
        - family
        - name
        - image
      properties:
        market_hash_name:
          type: string
          description: Full variant `market_hash_name`.
        family:
          type: string
          enum:
            - doppler
            - gamma_doppler
            - case_hardened
          description: Variant family.
        name:
          type: string
          description: Variant name (e.g. `Phase 2`, `Ruby`, `Tier 1`).
        phase:
          type: string
          description: Phase or gem name. Omitted for Case Hardened.
        color:
          type: string
          description: Hex accent color. Omitted for Case Hardened.
        paint_index:
          type: integer
          description: Paint kit index for this variant.
        image:
          type: string
          description: Owned image URL served from `cs2.sh`.
        steam_image:
          type: string
          description: Optional official Valve Economy/static image URL, emitted only when the exact variant origin is independently proven. Its absence does not remove the required owned `image`.
    SchemaItem:
      type: object
      description: One schema record, keyed by `market_hash_name` in the top-level `items` map. Fields that do not apply to the item are omitted.
      required:
        - market_hash_name
        - category
        - image
        - is_tradable
      properties:
        market_hash_name:
          type: string
          description: Canonical Steam market hash name (matches the price endpoints).
        category:
          type: string
          description: Item category (e.g. `skin`, `sticker`, `container`, `agent`).
        image:
          type: string
          description: Owned image URL served from `cs2.sh`.
        steam_image:
          type: string
          description: Optional official Valve Economy/static image URL, emitted only when the exact item origin is independently proven. Its absence does not remove the required owned `image`.
        is_tradable:
          type: boolean
          description: Whether the item can be traded.
        rarity:
          type: object
          description: Item rarity with `name`, `tier`, and `color`.
          required: [name, tier, color]
          properties:
            name:
              type: string
            tier:
              type: integer
            color:
              type: string
        collections:
          type: array
          description: Collections the item belongs to. Omitted when none.
          items:
            type: string
        containers:
          type: array
          description: Containers the item drops from. Omitted when none.
          items:
            type: string
        ids:
          type: object
          description: Marketplace catalog ids where known.
          properties:
            buff:
              type: integer
            youpin:
              type: integer
            c5game:
              type: integer
        def_index:
          type: integer
          description: Item definition index.
        base_name:
          type: string
          description: Base item name without the wear suffix. Skins only.
        weapon:
          type: string
          description: Weapon name. Skins only.
        finish:
          type: string
          description: Finish name. Skins only.
        paint_index:
          type: integer
          description: Paint kit index. Skins only; omitted on Doppler and Gamma Doppler base items.
        wears:
          type: array
          description: Wears the item exists in. Wear-carrying items only.
          items:
            type: string
        has_stattrak:
          type: boolean
          description: Whether a StatTrak version exists. Wear-carrying items only.
        has_souvenir:
          type: boolean
          description: Whether a Souvenir version exists. Wear-carrying items only.
        float_range:
          type: object
          description: Float bounds for this item. Wear-carrying items only.
          required: [min, max]
          properties:
            min:
              type: number
            max:
              type: number
        wear:
          type: string
          description: This item's wear (e.g. `Field-Tested`). Wear-carrying items only.
        wear_float_range:
          type: object
          description: Float bounds for this exact wear row, `float_range` clamped to this wear's bracket. Wear-carrying items only.
          required: [min, max]
          properties:
            min:
              type: number
            max:
              type: number
        stattrak:
          type: boolean
          description: Whether this row is the StatTrak version.
        souvenir:
          type: boolean
          description: Whether this row is the Souvenir version.
        variants:
          type: array
          description: Doppler / Gamma Doppler phases or Case Hardened tiers for this base item.
          items:
            $ref: '#/components/schemas/SchemaItemVariant'
        variant:
          type: object
          description: Back-link on a variant row to its base item.
          required: [family, name, of]
          properties:
            family:
              type: string
            name:
              type: string
            of:
              type: string
              description: Base item `market_hash_name`.
        phase:
          type: string
          description: Phase or gem name. Doppler and Gamma Doppler variant rows only.
        color:
          type: string
          description: Hex accent color. Doppler and Gamma Doppler variant rows only.
    SchemaResponse:
      type: object
      description: Response shape for `GET /v1/schema`, the full item schema with metadata keyed by `market_hash_name`.
      required:
        - schema_version
        - generation_id
        - generated_at
        - counts
        - rarities
        - collections
        - items
      properties:
        schema_version:
          type: string
          description: Schema version. Re-sync clients when it changes.
        generation_id:
          type: string
          description: Stable identifier for this immutable schema generation.
        generated_at:
          type: string
          format: date-time
          description: When this immutable schema generation was built. Compare `generation_id` to detect a generation change.
        counts:
          type: object
          description: Schema entity counts.
          required: [items, by_category, collections]
          properties:
            items:
              type: integer
              description: Number of item records.
            by_category:
              type: object
              description: Item count per category.
              additionalProperties:
                type: integer
            collections:
              type: integer
              description: Number of collections.
        rarities:
          type: array
          description: Rarity tiers.
          items:
            $ref: '#/components/schemas/SchemaRarity'
        collections:
          type: object
          description: Collection metadata keyed by collection name.
          additionalProperties:
            $ref: '#/components/schemas/SchemaCollection'
        items:
          type: object
          description: Item records keyed by `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: Error code (e.g., validation_error, unauthorized, rate_limited)
        message:
          type: string
          description: Human-readable error message
        request_id:
          type: string
          format: uuid
          description: Unique request identifier for support
        details:
          type: object
          description: Additional error details (structure varies by error type)
  responses:
    ValidationError:
      description: Invalid request parameters
      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: Missing or invalid API key
      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: Too many requests because the RPS bucket was exceeded
      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: Requested endpoint is outside your plan. Demo and Developer keys are restricted to the latest endpoints and `GET /v1/schema`; upgrade to Scale for full access.
      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: Service temporarily unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: service_unavailable
            message: cache unavailable
            request_id: 550e8400-e29b-41d4-a716-446655440000
    GatewayTimeout:
      description: Request timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: timeout
            message: query timeout
            request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: Item not found
      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