> ## Documentation Index
> Fetch the complete documentation index at: https://api.csboard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/listings — просмотр актуальных листингов маркетплейса CS2

> Получите актуальные доступные для покупки листинги CS2 с float, paint seed, наклейками и ценой продажи в USD. Фильтруйте по износу, категории, редкости, диапазону float и другим параметрам.

Эндпоинт listings возвращает все товары, доступные для покупки на маркетплейсе CSBoard прямо сейчас. Каждая запись содержит полные данные для оценки — значение float, paint seed, наклеенные стикеры с их износом — вместе с авторитетной ценой продажи в USD. Результаты разбиваются на страницы при помощи keyset-курсора, что позволяет надёжно пройти весь каталог даже по мере появления новых листингов.

**Требуется аутентификация.** Отправьте ключ как `Authorization: Bearer csb_pub_...`.

## Query-параметры

<ParamField query="search" type="string">
  Полнотекстовое совпадение по `market_hash_name` товара, например `AK-47 | Redline`.
</ParamField>

<ParamField query="category" type="string">
  Фильтр по категории товара, например `Rifle`, `Knife`, `Gloves`, `Pistol`.
</ParamField>

<ParamField query="wear" type="string">
  Фильтр по диапазону износа. Одно из: `Factory New`, `Minimal Wear`, `Field-Tested`, `Well-Worn`, `Battle-Scarred`.
</ParamField>

<ParamField query="rarity" type="string">
  Фильтр по уровню редкости, например `Classified`, `Covert`, `Extraordinary`.
</ParamField>

<ParamField query="min_price" type="number">
  Минимальная цена продажи в USD (включительно).
</ParamField>

<ParamField query="max_price" type="number">
  Максимальная цена продажи в USD (включительно).
</ParamField>

<ParamField query="min_float" type="number">
  Минимальное значение float (включительно). Принимает значения от `0.0` до `1.0`.
</ParamField>

<ParamField query="max_float" type="number">
  Максимальное значение float (включительно). Принимает значения от `0.0` до `1.0`.
</ParamField>

<ParamField query="stat_trak" type="string">
  Фильтр StatTrak™. `only` возвращает только предметы StatTrak™; `exclude` исключает их из результатов.
</ParamField>

<ParamField query="souvenir" type="string">
  Фильтр Souvenir. `only` возвращает только сувенирные предметы; `exclude` исключает их из результатов.
</ParamField>

<ParamField query="sort" type="string" default="id">
  Порядок сортировки. Одно из: `id` (стабильный по умолчанию), `newest`, `price_asc`, `price_desc`.
</ParamField>

<ParamField query="cursor" type="string">
  Keyset-курсор пагинации. Передайте значение `next_cursor` из предыдущего ответа, чтобы получить следующую страницу.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Количество результатов на странице. Минимум `1`, максимум `200`.
</ParamField>

## Поля ответа

<ResponseField name="items" type="Listing[]" required>
  Массив объектов листингов для этой страницы.

  <Expandable title="Listing object">
    <ResponseField name="id" type="string" required>
      Стабильный идентификатор листинга. Передайте его в `POST /v1/orders`, чтобы купить предмет.
    </ResponseField>

    <ResponseField name="market_hash_name" type="string" required>
      Steam market hash name, например `AK-47 | Redline (Minimal Wear)`.
    </ResponseField>

    <ResponseField name="wear" type="string | null">
      Диапазон износа: `Factory New`, `Minimal Wear`, `Field-Tested`, `Well-Worn` или `Battle-Scarred`. `null` для предметов без износа (например, некоторые ножи или перчатки).
    </ResponseField>

    <ResponseField name="doppler_phase" type="string | null">
      Фаза Doppler или Gamma Doppler, например `"Phase 2"`, `"Ruby"`, `"Emerald"`. `null` для предметов, не относящихся к Doppler.
    </ResponseField>

    <ResponseField name="float_value" type="number | null">
      Значение float от `0.0` до `1.0`. `null`, если неприменимо.
    </ResponseField>

    <ResponseField name="paint_seed" type="integer | null">
      Paint seed (индекс паттерна). `null`, если неприменимо.
    </ResponseField>

    <ResponseField name="stickers" type="Sticker[]" required>
      Наклеенные стикеры. Пустой массив, если их нет.

      <Expandable title="Sticker object">
        <ResponseField name="name" type="string">
          Название стикера, например `Crown (Foil)`.
        </ResponseField>

        <ResponseField name="image" type="string (URI)">
          URL изображения стикера на CDN.
        </ResponseField>

        <ResponseField name="slot" type="integer">
          Номер слота стикера, от `0` до `4`.
        </ResponseField>

        <ResponseField name="wear" type="number | null">
          Износ стикера от `0.0` до `1.0`. `null`, если износ стикера не был получен.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="price_usd" type="number" required>
      Авторитетная цена продажи в USD. Это ровно та сумма, которая будет списана при покупке этого листинга через `POST /v1/orders`.
    </ResponseField>

    <ResponseField name="category" type="string" required>
      Категория предмета, например `Rifle`, `Knife`, `Gloves`.
    </ResponseField>

    <ResponseField name="rarity" type="string">
      Уровень редкости, например `Classified`, `Covert`.
    </ResponseField>

    <ResponseField name="image" type="string (URI)">
      URL изображения предмета на CDN.
    </ResponseField>

    <ResponseField name="inspect_link" type="string">
      Ссылка для осмотра в Steam (`steam://rungame/...`) для этого предмета.
    </ResponseField>

    <ResponseField name="tradable" type="boolean" required>
      Можно ли сейчас обменивать предмет. `false` означает, что он находится в торговом холде.
    </ResponseField>

    <ResponseField name="tradable_at" type="datetime | null">
      Временная метка ISO 8601, когда предмет выйдет из торгового холда. `null`, если предмет уже доступен для обмена.
    </ResponseField>

    <ResponseField name="delivery" type="string" required>
      Ожидаемый режим доставки: `instant` (передаётся сразу) или `hold` (с учётом торгового холда Steam).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string | null" required>
  Непрозрачный keyset-курсор. Передайте его как query-параметр `cursor`, чтобы получить следующую страницу. `null` на последней странице.
</ResponseField>

## Пагинация

Этот эндпоинт использует **keyset-пагинацию**. Чтобы пройти все страницы:

1. Выполните первый запрос (без `cursor`).
2. Если `next_cursor` не равен null, повторите запрос с `cursor=<next_cursor>`.
3. Остановитесь, когда `next_cursor` станет `null` — вы дошли до последней страницы.

Keyset-пагинация стабильна: новые листинги, появляющиеся во время итерации, не приводят к дубликатам или пропущенным строкам.

## Пример запроса

```bash theme={null}
curl "https://csboard.com/v1/listings?category=Rifle&wear=Minimal+Wear&min_float=0.07&max_float=0.12&sort=price_asc&limit=20" \
  -H "Authorization: Bearer csb_pub_..."
```

## Пример ответа

```json theme={null}
{
  "items": [
    {
      "id": "itm_8841201",
      "market_hash_name": "AK-47 | Redline (Minimal Wear)",
      "wear": "Minimal Wear",
      "doppler_phase": null,
      "float_value": 0.0912,
      "paint_seed": 412,
      "stickers": [
        {
          "name": "Crown (Foil)",
          "image": "https://cdn.csboard.com/stickers/crown_foil.png",
          "slot": 0,
          "wear": 0.0
        }
      ],
      "price_usd": 14.37,
      "category": "Rifle",
      "rarity": "Classified",
      "image": "https://cdn.csboard.com/items/ak47_redline_mw.png",
      "inspect_link": "steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20...",
      "tradable": false,
      "tradable_at": "2026-07-06T12:00:00Z",
      "delivery": "hold"
    }
  ],
  "next_cursor": "eyJpZCI6Iml0bV84ODQxMjAxIn0="
}
```

## Коды ошибок

| HTTP-статус | Код                   | Значение                                                                                 |
| ----------- | --------------------- | ---------------------------------------------------------------------------------------- |
| 401         | `unauthorized`        | Отсутствует или некорректный API-ключ.                                                   |
| 429         | `rate_limit_exceeded` | Более 30 запросов/мин. Подождите количество секунд, указанное в заголовке `Retry-After`. |

<Tip>
  Значение `price_usd` у каждого листинга — это **авторитетная цена покупки**: оно отражает текущую цену продажи на момент запроса и ровно столько с вас спишут. Не используйте `min_price_usd` из эндпоинта `/prices` как оценку цены покупки — это значение может отставать.
</Tip>


## OpenAPI

````yaml GET /listings
openapi: 3.1.0
info:
  title: CSBoard API
  version: 1.0.0
  description: >-
    Market data over the CSBoard marketplace — live listings, floats, stickers,
    minAsk prices, FX rates — plus opt-in buying straight from your balance.
    Free to read, key-gated, built for automation.
  contact:
    name: CSBoard
    url: https://csboard.com/docs
servers:
  - url: https://csboard.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Status
    description: Liveness and freshness probes.
  - name: Market data
    description: Read the live catalog, prices, and FX rates.
  - name: Trading
    description: Buy listings from your CSBoard balance. Opt-in, key-gated.
  - name: Account
    description: Your balance, settled funds, and trading status.
paths:
  /listings:
    get:
      tags:
        - Market data
      summary: Live buyable listings
      description: >-
        Live buyable listings across the marketplace — each with float, paint
        seed, stickers, and the asking price in USD. Use keyset pagination via
        `cursor`.
      operationId: listListings
      parameters:
        - name: search
          in: query
          description: Full-text match on market hash name.
          schema:
            type: string
        - name: category
          in: query
          description: e.g. Rifle, Knife, Gloves.
          schema:
            type: string
        - name: wear
          in: query
          description: Item wear bucket.
          schema:
            type: string
            enum:
              - Factory New
              - Minimal Wear
              - Field-Tested
              - Well-Worn
              - Battle-Scarred
        - name: rarity
          in: query
          description: e.g. Classified, Covert.
          schema:
            type: string
        - name: min_price
          in: query
          description: Minimum price in USD.
          schema:
            type: number
        - name: max_price
          in: query
          description: Maximum price in USD.
          schema:
            type: number
        - name: min_float
          in: query
          description: Minimum float value.
          schema:
            type: number
        - name: max_float
          in: query
          description: Maximum float value.
          schema:
            type: number
        - name: stat_trak
          in: query
          description: Filter StatTrak™ items.
          schema:
            type: string
            enum:
              - only
              - exclude
        - name: souvenir
          in: query
          description: Filter Souvenir items.
          schema:
            type: string
            enum:
              - only
              - exclude
        - name: sort
          in: query
          description: Sort order. Default id.
          schema:
            type: string
            enum:
              - id
              - newest
              - price_asc
              - price_desc
            default: id
        - name: cursor
          in: query
          description: Keyset cursor from next_cursor.
          schema:
            type: string
        - name: limit
          in: query
          description: 1–200. Default 50.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: A page of listings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Listing'
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Pass back as `cursor` to fetch the next page. Null on the
                      last page.
                required:
                  - items
                  - next_cursor
              example:
                items:
                  - id: itm_8841201
                    market_hash_name: AK-47 | Redline (Minimal Wear)
                    wear: Minimal Wear
                    doppler_phase: null
                    float_value: 0.0912
                    paint_seed: 412
                    stickers:
                      - name: Crown (Foil)
                        image: https://cdn.csboard.com/stickers/crown_foil.png
                        slot: 0
                        wear: 0
                    price_usd: 14.37
                    category: Rifle
                    rarity: Classified
                    image: https://cdn.csboard.com/items/ak47_redline_mw.png
                    inspect_link: >-
                      steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20...
                    tradable: false
                    tradable_at: '2026-07-06T12:00:00Z'
                    delivery: hold
                next_cursor: eyJpZCI6Iml0bV84ODQxMjAxIn0=
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Listing:
      type: object
      properties:
        id:
          type: string
          description: Stable listing id. Pass to POST /v1/orders.
        market_hash_name:
          type: string
        wear:
          type:
            - string
            - 'null'
          enum:
            - Factory New
            - Minimal Wear
            - Field-Tested
            - Well-Worn
            - Battle-Scarred
            - null
        doppler_phase:
          type:
            - string
            - 'null'
          description: Doppler / Gamma Doppler phase, e.g. "Phase 2", "Ruby", or null.
        float_value:
          type:
            - number
            - 'null'
        paint_seed:
          type:
            - integer
            - 'null'
        stickers:
          type: array
          items:
            $ref: '#/components/schemas/Sticker'
        price_usd:
          type: number
          description: >-
            Authoritative asking price in USD. Equals the amount charged if you
            buy this listing.
        category:
          type: string
        rarity:
          type: string
        image:
          type: string
          format: uri
        inspect_link:
          type: string
        tradable:
          type: boolean
        tradable_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the item leaves trade hold. Null if already tradable.
        delivery:
          type: string
          enum:
            - instant
            - hold
      required:
        - id
        - market_hash_name
        - price_usd
        - category
        - delivery
        - stickers
        - tradable
    Sticker:
      type: object
      properties:
        name:
          type: string
        image:
          type: string
          format: uri
        slot:
          type: integer
          minimum: 0
          maximum: 4
        wear:
          type:
            - number
            - 'null'
          description: Sticker wear 0–1, or null if unscraped.
      required:
        - name
        - image
        - slot
        - wear
    Error:
      type: object
      description: >-
        All errors return { code, detail }. Some carry extra fields (e.g.
        price_moved adds current_total_usd, insufficient_balance adds
        required_usd/current_usd).
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. rate_limit_exceeded,
            trading_not_enabled, price_moved.
        detail:
          type: string
          description: Human-readable explanation.
      required:
        - code
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key.
    RateLimited:
      description: Rate limit exceeded. Includes a Retry-After header.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limit_exceeded
            message: Too many requests.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send your key as a Bearer token on every request: `Authorization: Bearer
        csb_pub_...`. Generate keys in your CSBoard profile.

````