cspriceapi-com Float Ranged API

openapi: 3.2.0
info:
  title: CS Price Float Ranged 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: Float Ranged
  description: 'Float-range filtered listing prices (buckets such as `0.00-0.07`),

    including listing counts, phase translations for Doppler skins, and fade

    percentage for Fade skins.


    **Plan: Pro** (included in Enterprise).'
paths:
  /v2/prices/float-ranged:
    get:
      tags:
      - Float Ranged
      summary: Get float-ranged prices v2 (Pro)
      description: 'Returns float-ranged listing prices (v2).


        This v2 payload is intentionally slim and only includes:

        `market_hash_name`, `float_range`, `phase`, `fade`, `count`,

        `price_rmb` and `updated_at`.


        The `phase` field is translated to English where applicable.

        `fade` is the fade percentage for Fade skins (otherwise `null`).'
      operationId: getFloatRangedPricesV2
      responses:
        '200':
          description: Successful response with float-ranged v2 data.
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloatRangedV2PricesResponse'
              examples:
                ok:
                  value:
                    data:
                    - market_hash_name: Glock-18 | Gamma Doppler (Factory New)
                      float_range: 0.00-0.07
                      phase: Phase 2
                      fade: null
                      count: 12
                      price_rmb: '1230.0000'
                      updated_at: '2026-04-21T12:00:00.000Z'
                    - market_hash_name: AWP | Fade (Factory New)
                      float_range: 0.00-0.01
                      phase: null
                      fade: 81.7
                      count: 3
                      price_rmb: '5088.8200'
                      updated_at: '2026-08-06T12:00:00.000Z'
                    source: Float Ranged
                    requestor: customer@example.com
                    plan: pro
                    timestamp: '2026-04-21T12:20:35.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/prices/buff163/float-ranged:
    get:
      tags:
      - Float Ranged
      summary: Get Buff163 float-ranged prices (Pro)
      description: 'Buff163 listing prices per float range, Fade % range, Doppler phase and

        pattern tier: lowest listing (`price_rmb`), average of the 10 cheapest

        listings and the real listing count in that range.


        Ranges are Buff''s fixed buckets (e.g. `0.15-0.18`, the same buckets as

        `/v2/prices/float-ranged`). Fade skins come as a matrix of float and

        Fade ranges; `null` marks the axis that is not limited. `price_rmb` is

        `null` when nothing is listed in that range right now.


        `phase` holds Doppler / Gamma Doppler phases, `tier` pattern tiers

        (`T1`–`T4` Case Hardened / Heat Treated, `T1`–`T10` Marble Fade,

        `T1`–`T6` Crimson Kimono). Without `market_hash_name` the response

        covers ~77,000 ranges for ~15,700 skins (use `Accept-Encoding: gzip`).

        Data refreshes about every 10 minutes.'
      operationId: getBuffFloatRangedPrices
      parameters:
      - name: market_hash_name
        in: query
        required: false
        description: One or more skins (comma-separated or repeated, max 100). Omit for all skins.
        schema:
          type: string
        example: ★ Karambit | Doppler (Factory New)
      responses:
        '200':
          description: Successful response with Buff163 float-ranged listing prices.
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuffFloatRangedResponse'
              examples:
                ok:
                  value:
                    data:
                    - market_hash_name: ★ Karambit | Doppler (Factory New)
                      goods_id: 42998
                      float_range: 0.00-0.01
                      fade_range: null
                      phase: Ruby
                      tier: null
                      count: 18
                      price_rmb: '52200.00'
                      avg_top10_price_rmb: '57249.60'
                      updated_at: '2026-10-18T08:12:22.000Z'
                    - market_hash_name: ★ M9 Bayonet | Fade (Factory New)
                      goods_id: 33812
                      float_range: 0.00-0.01
                      fade_range: 99-100
                      phase: null
                      tier: null
                      count: 9
                      price_rmb: '9500.00'
                      avg_top10_price_rmb: '10480.00'
                      updated_at: '2026-10-18T08:12:22.000Z'
                    source: Buff163
                    requestor: customer@example.com
                    plan: pro
                    timestamp: '2026-10-18T08:20:00.000Z'
        '400':
          description: Too many market_hash_name values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Too many market_hash_name values (max 100)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    BuffFloatRangedResponse:
      allOf:
      - $ref: '#/components/schemas/BaseWrapper'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/BuffFloatRangedItem'
          source:
            type: string
            enum:
            - Buff163
        required:
        - data
    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
    FloatRangedV2Item:
      type: object
      description: Float-range filtered listing snapshot (v2).
      properties:
        market_hash_name:
          type: string
          example: Glock-18 | Gamma Doppler (Factory New)
        float_range:
          type: string
          description: Float-range bucket/filter.
          example: 0.00-0.07
        phase:
          $ref: '#/components/schemas/Phase'
        fade:
          type: number
          nullable: true
          description: 'Fade percentage for Fade skins (e.g. `81.7`). `null` for non-Fade

            items.

            '
          example: 81.7
        count:
          type: integer
          nullable: true
          example: 12
        price_rmb:
          allOf:
          - $ref: '#/components/schemas/DecimalString'
          nullable: true
          description: Lowest listing price in CNY (RMB) for this float range.
          example: '1230.0000'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
      required:
      - market_hash_name
      - float_range
      - phase
      - updated_at
    BuffFloatRangedItem:
      type: object
      properties:
        market_hash_name:
          type: string
        goods_id:
          type: integer
          description: Buff goods_id.
        float_range:
          type:
          - string
          - 'null'
          description: Float bucket, e.g. "0.15-0.18"; null = all floats.
        fade_range:
          type:
          - string
          - 'null'
          description: Fade % bucket, e.g. "97-99"; null = all fades.
        phase:
          type:
          - string
          - 'null'
          description: Doppler / Gamma Doppler phase.
        tier:
          type:
          - string
          - 'null'
          description: Pattern tier ("T1"–"T10").
        count:
          type: integer
          description: Listings in this range.
        price_rmb:
          description: Lowest listing in CNY, null when nothing is listed.
          oneOf:
          - $ref: '#/components/schemas/DecimalString'
          - type: 'null'
        avg_top10_price_rmb:
          description: Average of the 10 cheapest listings in CNY.
          oneOf:
          - $ref: '#/components/schemas/DecimalString'
          - type: 'null'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
    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'
    BaseWrapper:
      type: object
      description: Envelope fields returned by every `GET /v1/prices/*` response.
      properties:
        source:
          type: string
          description: Human-readable marketplace identifier.
        requestor:
          type: string
          format: email
          description: Email address associated with the API key making the call.
          example: customer@example.com
        plan:
          type: string
          description: Plan of the API key (e.g. `free`, `pro`, `enterprise`).
          example: pro
        timestamp:
          allOf:
          - $ref: '#/components/schemas/UpdatedAt'
          description: Server time when this response was produced.
      required:
      - source
      - timestamp
    Phase:
      type: string
      nullable: true
      description: 'Doppler phase, normalised to English. Empty string or `null` for

        non-phase items.

        '
      example: Phase 2
    FloatRangedV2PricesResponse:
      allOf:
      - $ref: '#/components/schemas/BaseWrapper'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/FloatRangedV2Item'
          source:
            type: string
            enum:
            - Float Ranged
        required:
        - data
    UpdatedAt:
      type: string
      format: date-time
      description: ISO-8601 UTC timestamp (millisecond precision).
      example: '2026-04-21T12:06:35.000Z'
  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
  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`.

        '