cspriceapi-com Indexes API

openapi: 3.2.0
info:
  title: CS Price Indexes API
  version: 1.6.0
  description: 'Public price API for the CS2 (Counter-Strike 2) skin ecosystem.


    Latest listing prices are available via a single item-centric endpoint

    `GET` / `POST` `/v1/prices/latest` (optional `markets` filter). Use

    `/v1/prices/search` for one skin with Doppler phase expansion, plus

    buy-orders, float-ranged, price history, YouPin market-cap indexes and

    market-sales export.


    Subscription customers can additionally download a daily **ZIP export** of

    historical marketplace sales (`/v1/market-sales/export`) as three CSV files

    (sales, stickers, keychains) covering the last 24 hours.


    ## Subscription plans


    API access is grouped by plan. Higher tiers include all endpoints from lower

    tiers:


    | Plan | Included categories |

    |------|---------------------|

    | **Basic** | Listing Prices |

    | **Pro** | Basic + Buyorder Prices + Float Ranged |

    | **Enterprise** | Pro + Price History + Sales Data (full API access) |


    Each API key is issued for a specific plan and may be further restricted via

    endpoint ACL (`allowed_endpoints`).


    ## Authentication


    Every non-documentation endpoint requires an API key in the `x-api-key`

    request header. Keys are issued per customer and optionally scoped to a

    subset of endpoints (endpoint ACL). Every key is limited to 10 requests

    per second; there is no daily or monthly cap. Requests over the limit get

    `429` with a `Retry-After: 1` header.


    ## Response format stability


    All response shapes documented here reflect what the server **currently**

    returns. In particular:


    - Numeric fields for prices, percentage changes, averages and liquidity

    are serialized as **strings**, not numbers.

    Example: `"price_rmb": "7333.0000"`. Clients must parse them as

    fixed-point / arbitrary-precision decimals.

    - `stattrak` and `souvenir` are serialized as **integers** (`0` or `1`),

    not booleans.

    - `updated_at` is ISO-8601 UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`).

    - `liquidity` is an internal liquidity score and may be `null` if

    unavailable for that skin.'
  contact:
    name: CS Price API Support
    url: https://cspriceapi.com
servers:
- url: https://api.cspriceapi.com
  description: Production
- url: http://localhost:8080
  description: Local development
security:
- ApiKeyAuth: []
tags:
- name: Indexes
  description: 'Aggregate YouPin market-cap time series for the CS2 skin economy

    (`price × listing count`, outlier-filtered). Same series as the public

    Market Index page.


    **Plan: Enterprise**.'
paths:
  /v1/indexes/market-cap:
    get:
      tags:
      - Indexes
      summary: YouPin total market cap (Enterprise)
      description: 'Daily or hourly **aggregate YouPin market cap** — the sum of

        `price × listing count` across the YouPin898 catalogue, in CNY.


        This is the same cleaned series shown on the public Market Index page:


        - unit price must be `> 0` and `< 1,000,000` RMB (drops joke listings)

        - at least **2** active listings (a single seller cannot move the index)

        - only skins that exist in the internal catalogue


        Daily data is cached server-side for 6 hours. Hourly data is cached for

        10 minutes and reads the pre-aggregated hourly table when available.


        `market_cap_rmb` is a decimal **string**. `cleaned` is `true` when the

        outlier filters were applied; `false` means a fast fallback from the

        precomputed daily table was used.'
      operationId: getYoupinMarketCap
      parameters:
      - name: resolution
        in: query
        required: false
        schema:
          type: string
          enum:
          - daily
          - hourly
          default: daily
        description: Point density. Defaults to `daily`.
      - name: days
        in: query
        required: false
        schema:
          type: integer
          minimum: 7
          maximum: 365
          default: 30
        description: Lookback for `resolution=daily` (clamped to 7–365).
      - name: hours
        in: query
        required: false
        schema:
          type: integer
          minimum: 12
          maximum: 168
          default: 48
        description: Lookback for `resolution=hourly` (clamped to 12–168).
      responses:
        '200':
          description: Aggregate YouPin market-cap series.
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=300
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketCapResponse'
              examples:
                daily:
                  summary: Daily resolution (30d)
                  value:
                    currency: CNY
                    resolution: daily
                    days: 30
                    cleaned: true
                    formula: sum(price * listing_count)
                    filters:
                      max_price_rmb: 1000000
                      min_listings: 2
                    current:
                      day: '2026-09-05'
                      market_cap_rmb: '1854321000.2500'
                      listing_count: 412003
                    change_7d: '1.24'
                    change_range: '-2.10'
                    from: '2026-08-07'
                    to: '2026-09-05'
                    count: 2
                    data:
                    - day: '2026-08-07'
                      market_cap_rmb: '1894000000.0000'
                      listing_count: 401220
                    - day: '2026-09-05'
                      market_cap_rmb: '1854321000.2500'
                      listing_count: 412003
                    source: YouPin Market Cap
                    requestor: customer@example.com
                    plan: enterprise
                    timestamp: '2026-09-05T16:00:00.000Z'
                hourly:
                  summary: Hourly resolution (48h)
                  value:
                    currency: CNY
                    resolution: hourly
                    hours: 48
                    cleaned: true
                    formula: sum(price * listing_count)
                    filters:
                      max_price_rmb: 1000000
                      min_listings: 2
                    current:
                      ts: 1757088000
                      hour: '2026-09-05T16:00:00.000Z'
                      market_cap_rmb: '1854321000.2500'
                      listing_count: 412003
                    change_7d: null
                    change_range: '0.18'
                    count: 2
                    data:
                    - ts: 1757001600
                      hour: '2026-09-04T16:00:00.000Z'
                      market_cap_rmb: '1851000000.0000'
                      listing_count: 410880
                    - ts: 1757088000
                      hour: '2026-09-05T16:00:00.000Z'
                      market_cap_rmb: '1854321000.2500'
                      listing_count: 412003
                    source: YouPin Market Cap
                    requestor: customer@example.com
                    plan: enterprise
                    timestamp: '2026-09-05T16:05:00.000Z'
        '400':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                resolution:
                  value:
                    error: 'Invalid parameter: resolution (expected daily|hourly)'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded (10 requests per second per key). Retry after 1 second.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            perSecond:
              value:
                error: Rate limit exceeded (10 requests per second)
    InternalError:
      description: Internal server error – temporary upstream failure, etc.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            generic:
              value:
                error: Internal server error
            db:
              value:
                error: DB error
    Unauthorized:
      description: Missing, invalid, disabled or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              value:
                error: Missing API key
            invalid:
              value:
                error: Invalid API key
            disabled:
              value:
                error: API key disabled
            expired:
              value:
                error: API key expired
    Forbidden:
      description: The API key is valid but is not allowed to call this endpoint (endpoint ACL).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            acl:
              value:
                error: Endpoint not allowed for this API key
  schemas:
    Error:
      type: object
      description: 'Current error envelope. A future release may add an optional

        `error_details` object next to `error`; the `error` string will

        remain for backwards compatibility.

        '
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: Invalid API key
      required:
      - error
    DecimalString:
      type: string
      description: 'Fixed-point decimal value serialized as a string (preserves precision

        across languages). Parse with an arbitrary-precision decimal library;

        do **not** parse as a native float.

        '
      pattern: ^-?\d+(\.\d+)?$
      example: '1234.5600'
    MarketCapResponse:
      type: object
      description: Aggregate YouPin market-cap envelope.
      properties:
        currency:
          type: string
          enum:
          - CNY
        resolution:
          type: string
          enum:
          - daily
          - hourly
        days:
          type: integer
          description: Present for `resolution=daily`.
        hours:
          type: integer
          description: Present for `resolution=hourly`.
        cleaned:
          type: boolean
          description: '`true` when outlier filters were applied. `false` when the

            precomputed `market_cap_daily` fallback was used.

            '
        formula:
          type: string
          example: sum(price * listing_count)
        filters:
          type: object
          properties:
            max_price_rmb:
              type: integer
              example: 1000000
            min_listings:
              type: integer
              example: 2
        current:
          description: Latest point in the returned series, or `null` if empty.
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MarketCapPointDaily'
          - $ref: '#/components/schemas/MarketCapPointHourly'
        change_7d:
          allOf:
          - $ref: '#/components/schemas/DecimalString'
          nullable: true
          description: Percent change vs ~7 days earlier. `null` if not enough history.
        change_range:
          allOf:
          - $ref: '#/components/schemas/DecimalString'
          nullable: true
          description: Percent change from the first to the last point in this response.
        from:
          type: string
          format: date
          nullable: true
          description: First daily point (`resolution=daily` only).
        to:
          type: string
          format: date
          nullable: true
          description: Last daily point (`resolution=daily` only).
        count:
          type: integer
        data:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/MarketCapPointDaily'
            - $ref: '#/components/schemas/MarketCapPointHourly'
        source:
          type: string
          example: YouPin Market Cap
        requestor:
          type: string
          format: email
        plan:
          type: string
        timestamp:
          $ref: '#/components/schemas/UpdatedAt'
      required:
      - currency
      - resolution
      - cleaned
      - count
      - data
      - source
      - timestamp
    UpdatedAt:
      type: string
      format: date-time
      description: ISO-8601 UTC timestamp (millisecond precision).
      example: '2026-04-21T12:06:35.000Z'
    MarketCapPointDaily:
      type: object
      properties:
        day:
          type: string
          format: date
          example: '2026-09-05'
        market_cap_rmb:
          allOf:
          - $ref: '#/components/schemas/DecimalString'
          description: Aggregate YouPin market cap for that day, in CNY.
        listing_count:
          type: integer
          nullable: true
          description: Sum of listing counts included in the cap.
          example: 412003
      required:
      - day
      - market_cap_rmb
    MarketCapPointHourly:
      type: object
      properties:
        ts:
          type: integer
          description: Unix timestamp of the hour bucket (UTC).
          example: 1757088000
        hour:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp for the hour bucket.
        market_cap_rmb:
          allOf:
          - $ref: '#/components/schemas/DecimalString'
          description: Aggregate YouPin market cap for that hour, in CNY.
        listing_count:
          type: integer
          nullable: true
          example: 412003
      required:
      - ts
      - hour
      - market_cap_rmb
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key issued per customer. Send it in the `x-api-key` header on every

        request. Every key is limited to 10 requests per second (no daily cap)

        and can be endpoint-scoped (ACL). Inactive or expired keys will be rejected

        with `401`.

        '