cspriceapi-com Sales Data API

openapi: 3.2.0
info:
  title: CS Price Sales Data 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: Sales Data
  description: 'Daily ZIP/CSV bulk export of historical marketplace sales.

    Requires a subscription API key scoped to `/v1/market-sales/export`.


    **Plan: Enterprise** (includes all API endpoints).'
paths:
  /v1/market-sales/search:
    get:
      tags:
      - Sales Data
      summary: Look up sales by market_hash_name (Enterprise)
      description: 'Returns recent marketplace **sales** for up to **5**

        `market_hash_name` values, including nested `stickers` and `keychains` per sale.


        At most **50** most recent sales are returned **per** `market_hash_name`

        (so up to 250 rows when querying 5 names). Results are ordered by

        `sold_at` descending.


        Only sales from the **last 72 hours** are returned (**24 hours** for 2-day test keys).

        Older sales are not available through this endpoint; a historical sales archive

        (deduplicated CSV per month) is available on request.


        Pass one or more names via repeated query params or a comma-separated list:


        ```

        ?market_hash_name=AK-47 | Redline (Field-Tested)

        ?market_hash_name=AK-47 | Redline (Field-Tested)&market_hash_name=M4A4 | Temukau (Minimal Wear)

        ?market_hash_name=AK-47 | Redline (Field-Tested),M4A4 | Temukau (Minimal Wear)

        ```


        Optional filters:


        - `marketplace`: `csfloat`, `youpin`, `skinport`

        - `float_min`, `float_max`: float range (inclusive)

        - `paint_index`: one or more paint indexes

        - `paint_seed`: one or more paint seeds / patterns

        - `price_min`, `price_max`: sale price range in **cents**


        `price` and `reference_price` are in **cents**. `sale_id`, `sticker_id` and

        `keychain_id` are returned as **strings** to avoid precision loss.'
      operationId: searchMarketSales
      parameters:
      - name: market_hash_name
        in: query
        required: true
        description: 'Steam `market_hash_name` to look up. Repeat up to 5 times, or pass a

          comma-separated list (max 5 unique names).

          '
        schema:
          type: array
          minItems: 1
          maxItems: 5
          items:
            type: string
            minLength: 1
        style: form
        explode: true
        examples:
          single:
            value:
            - AK-47 | Redline (Field-Tested)
          multiple:
            value:
            - AK-47 | Redline (Field-Tested)
            - M4A4 | Temukau (Minimal Wear)
      - name: marketplace
        in: query
        required: false
        schema:
          type: string
          enum:
          - csfloat
          - youpin
          - skinport
      - name: float_min
        in: query
        required: false
        schema:
          type: number
        description: Minimum `float_value` (inclusive).
      - name: float_max
        in: query
        required: false
        schema:
          type: number
        description: Maximum `float_value` (inclusive).
      - name: paint_index
        in: query
        required: false
        description: 'Paint index filter. Repeat the parameter or pass a comma-separated list.

          '
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: true
      - name: paint_seed
        in: query
        required: false
        description: 'Paint seed / pattern filter. Repeat the parameter or pass a comma-separated list.

          '
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: true
      - name: price_min
        in: query
        required: false
        schema:
          type: integer
        description: Minimum sale price in cents (inclusive).
      - name: price_max
        in: query
        required: false
        schema:
          type: integer
        description: Maximum sale price in cents (inclusive).
      responses:
        '200':
          description: Matching sales with nested stickers and keychains.
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketSalesSearchResponse'
        '400':
          description: Missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/market-sales/export:
    get:
      tags:
      - Sales Data
      summary: ZIP export of the last 24 hours (Enterprise)
      description: 'Returns a **ZIP archive** (`market-sales-export.zip`) with three CSV files

        for subscription customers who replicate the dataset locally once per day.


        | File in ZIP | Contents | Typical row count |

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

        | `sales.csv` | Sale events | ~100k / 24h |

        | `stickers.csv` | Stickers attached to sales | ~60k / 24h |

        | `keychains.csv` | Keychains attached to sales | ~1k / 24h |


        Always exports **all rows from the last 24 hours**

        in a single request (~6 MB compressed ZIP). No pagination.


        Join the CSVs locally on `(marketplace, sale_id, sold_at)`.


        Requires `x-api-key`. The key must include `/v1/market-sales/export` in its

        `allowed_endpoints` (or `*`).


        ```bash

        curl -H "x-api-key: YOUR_KEY" \

        "https://api.cspriceapi.com/v1/market-sales/export" \

        -o market-sales-export.zip

        unzip market-sales-export.zip

        ```


        See component schemas `MarketSalesCsvSalesRow`, `MarketSalesCsvStickersRow`

        and `MarketSalesCsvKeychainsRow` for the exact column layout.


        **Notes**


        - `price` and `reference_price` are in **cents** (integer).

        - `sale_id`, `sticker_id`, `keychain_id` are large integers serialized as

        **strings** in CSV to avoid JavaScript precision loss.

        - `marketplace` values: `csfloat`, `youpin`, `skinport`.'
      operationId: exportMarketSalesZip
      responses:
        '200':
          description: 'ZIP archive containing `sales.csv`, `stickers.csv` and `keychains.csv`

            (each with a header row). Row counts are also exposed via response headers.

            '
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, no-store
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="market-sales-export.zip"
            X-Sales-Row-Count:
              schema:
                type: integer
                example: 97596
              description: Data rows in `sales.csv` (excludes header).
            X-Sticker-Row-Count:
              schema:
                type: integer
                example: 61007
            X-Keychain-Row-Count:
              schema:
                type: integer
                example: 1228
            X-Window-Hours:
              schema:
                type: integer
                example: 24
            X-Window-Start:
              schema:
                type: string
                format: date-time
              description: Start of the export window (UTC).
            X-Window-End:
              schema:
                type: string
                format: date-time
              description: Time the export was generated (UTC).
          content:
            application/zip:
              schema:
                type: string
                format: binary
              example: (binary ZIP – see CSV schemas for contained file layout)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    MarketSalesCsvStickersRow:
      description: One row in `stickers.csv` inside the ZIP export.
      type: object
      properties:
        marketplace:
          type: string
        sale_id:
          type: string
        sold_at:
          type: string
        position_idx:
          type: integer
        sticker_id:
          type: string
        slot:
          type: integer
        sticker_name:
          type: string
        wear:
          type: number
        offset_x:
          type: number
        offset_y:
          type: number
        rotation:
          type: number
        reference_price:
          type: integer
          description: Reference price in cents.
        reference_quantity:
          type: integer
        reference_updated:
          type: string
        fetched_at:
          type: string
    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
    MarketSalesSearchResponse:
      type: object
      properties:
        market_hash_names:
          type: array
          items:
            type: string
        count:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/MarketSaleSearchItem'
        source:
          type: string
          example: Market Sales
        requestor:
          type: string
          format: email
        plan:
          type: string
        timestamp:
          $ref: '#/components/schemas/UpdatedAt'
      required:
      - market_hash_names
      - count
      - data
      - source
      - timestamp
    MarketSalesCsvKeychainsRow:
      description: One row in `keychains.csv` inside the ZIP export.
      type: object
      properties:
        marketplace:
          type: string
        sale_id:
          type: string
        sold_at:
          type: string
        position_idx:
          type: integer
        keychain_id:
          type: string
        slot:
          type: integer
        keychain_name:
          type: string
        pattern:
          type: integer
        offset_x:
          type: number
        offset_y:
          type: number
        offset_z:
          type: number
        reference_price:
          type: integer
        reference_quantity:
          type: integer
        reference_updated:
          type: string
        fetched_at:
          type: string
    UpdatedAt:
      type: string
      format: date-time
      description: ISO-8601 UTC timestamp (millisecond precision).
      example: '2026-04-21T12:06:35.000Z'
    MarketSaleSearchItem:
      allOf:
      - $ref: '#/components/schemas/MarketSalesCsvSalesRow'
      - type: object
        properties:
          stickers:
            type: array
            items:
              $ref: '#/components/schemas/MarketSalesCsvStickersRow'
          keychains:
            type: array
            items:
              $ref: '#/components/schemas/MarketSalesCsvKeychainsRow'
        required:
        - stickers
        - keychains
    MarketSalesCsvSalesRow:
      description: One row in `sales.csv` inside the ZIP export.
      type: object
      properties:
        marketplace:
          type: string
          enum:
          - csfloat
          - youpin
          - skinport
        sale_id:
          type: string
          description: UInt64 as string.
        market_hash_name:
          type: string
        price:
          type: integer
          description: Sale price in cents.
        sold_at:
          type: string
          example: '2026-07-06 12:59:12.668'
        def_index:
          type: integer
        paint_index:
          type: integer
        paint_seed:
          type: integer
        float_value:
          type: number
        is_stattrak:
          type: integer
          enum:
          - 0
          - 1
        is_souvenir:
          type: integer
          enum:
          - 0
          - 1
        rarity:
          type: integer
        quality:
          type: integer
        cs2_img:
          type: string
        fetched_at:
          type: string
          example: '2026-07-06 12:59:12.668'
  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`.

        '