> ## 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.

# Автоматическая покупка CS2-скинов с баланса CSBoard

> Размещайте автоматические ордера со списанием с баланса CSBoard, защищайтесь от движений цены и гарантируйте идемпотентную доставку с помощью POST /v1/orders.

Покупка через API CSBoard позволяет приобретать CS2-скины программно — прямо с баланса, с атомарной защитой от перерасхода и встроенной идемпотентностью. Перед первым ордером необходимо выполнить короткую разовую настройку. Следуйте шагам ниже по порядку.

<Warning>
  Стандартный ключ для чтения **никогда** не может расходовать деньги. Торговля намеренно сделана opt-in — утёкший или скомпрометированный ключ для чтения не сможет размещать ордера или опустошить ваш баланс, пока вы явно не включите эту возможность.
</Warning>

## Настройка

<Steps>
  <Step title="Включите торговлю для ключа">
    Перейдите в [API-профиль](https://csboard.com/profile?tab=api) и переключите тумблер **buying** для нужного ключа. До этого каждый вызов `POST /v1/orders` будет возвращать `403 trading_not_enabled`.
  </Step>

  <Step title="Привяжите аккаунт Steam и trade URL">
    Ордера доставляются напрямую в Steam, поэтому в профиле должны быть привязаны Steam-аккаунт и действующий trade URL. Без этого API возвращает `400 steam_account_required`.
  </Step>

  <Step title="Пополните баланс CSBoard">
    Покупки списываются с вашего существующего баланса CSBoard. Пополняйте его на сайте — через сам API нет пути оплаты картой или криптовалютой.
  </Step>

  <Step title="Найдите листинги для покупки">
    Запросите `GET /v1/listings`, чтобы найти предметы и собрать их поля `id`. Каждое значение `id` в ответе — это стабильная ссылка, которую вы передаёте непосредственно в эндпоинт ордеров.

    ```bash theme={null}
    curl "https://csboard.com/v1/listings?search=AK-47%20Redline&wear=Minimal%20Wear&sort=price_asc&limit=5" \
      -H "Authorization: Bearer csb_pub_..."
    ```
  </Step>

  <Step title="Разместите ордер">
    Отправьте POST со списком ID листингов в `/v1/orders`. Включите `max_price_usd` и `Idempotency-Key` — оба подробно объясняются ниже.

    ```bash theme={null}
    curl -X POST https://csboard.com/v1/orders \
      -H "Authorization: Bearer csb_pub_..." \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f" \
      -d '{"item_ids":["itm_8841201"],"max_price_usd":20.00}'
    ```
  </Step>
</Steps>

***

## Защита от перерасхода

Вам всегда списывается **актуальная цена в момент исполнения**, а не цена, которую вы видели при просмотре листингов. Рынки движутся — листинг, который вы получили 30 секунд назад, мог быть перевыставлен по более высокой цене к моменту исполнения ордера.

Используйте `max_price_usd` как потолок общей суммы. Списание атомарно: если на момент исполнения актуальная сумма превышает ваш потолок, весь ордер отклоняется с `400 price_moved` — ничего не списывается и ни один предмет не передаётся.

<Tip>
  Всегда читайте `price_usd` из `GET /v1/listings` непосредственно перед размещением ордера — это значение является авторитетным и равняется точной сумме списания. Эндпоинт `/v1/prices` возвращает индикативный сгруппированный снапшот, который может отставать от живой цены по предмету.
</Tip>

Если цена изменилась и вы получили `400`, в теле ответа есть `current_total_usd`, чтобы вы могли решить, перепосылать ли запрос с более высоким потолком или прервать сделку:

```json theme={null}
{
  "code": "price_moved",
  "message": "Live total 31.20 exceeds max_price_usd 30.00.",
  "current_total_usd": 31.20
}
```

***

## Идемпотентность

Сетевые сбои случаются. Без идемпотентности повтор после таймаута может купить один и тот же предмет дважды. Чтобы этого избежать, отправляйте уникальный заголовок `Idempotency-Key` с каждым запросом ордера.

* Если сервер получает два запроса с одинаковым ключом, он воспроизводит исходный результат ордера — покупка никогда не выполняется повторно.
* Также можно передать `idempotency_key` в теле запроса вместо заголовка; эффект одинаковый.
* Используйте UUID v4, сгенерированный на каждую попытку ордера, а не на каждый повтор.

```bash theme={null}
curl -X POST https://csboard.com/v1/orders \
  -H "Authorization: Bearer csb_pub_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f" \
  -d '{
    "item_ids": ["itm_8841201", "itm_8841340"],
    "max_price_usd": 30.00
  }'
```

***

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

Успешный ордер возвращает `200` с деталями ордера и вашим оставшимся балансом:

```json theme={null}
{
  "order_id": "ord_01J9Z3K8Q2",
  "status": "processing",
  "items": [
    {
      "item_id": "itm_8841201",
      "charged_usd": 14.37,
      "delivery": "hold"
    },
    {
      "item_id": "itm_8841340",
      "charged_usd": 12.10,
      "delivery": "instant"
    }
  ],
  "total_charged_usd": 26.47,
  "balance_after_usd": 73.53,
  "created_at": "2026-06-29T17:12:04Z"
}
```

***

## Доставка

Каждый предмет в ответе ордера содержит поле `delivery`:

* **`instant`** — предмет торгуем прямо сейчас и будет отправлен по вашему Steam trade URL немедленно.
* **`hold`** — предмет находится под trade hold в Steam. Смотрите поле `tradable_at` листинга (ISO 8601 timestamp), чтобы узнать, когда он станет торгуемым.

***

## Справочник ошибок

| Код                      | HTTP-статус | Значение                                                                       |
| ------------------------ | ----------- | ------------------------------------------------------------------------------ |
| `price_moved`            | 400         | Актуальная цена превысила `max_price_usd` — ответ содержит `current_total_usd` |
| `insufficient_balance`   | 402         | Ваш баланс CSBoard ниже общей суммы ордера                                     |
| `steam_account_required` | 400         | К профилю не привязан Steam-аккаунт или trade URL                              |
| `trading_not_enabled`    | 403         | У API-ключа не включена покупка                                                |

***

## Дальнейшие шаги

* [Автоматизация покупок с ботами и мониторами цен](/guides/automation)
* [Запрос актуальных листингов и цен](/guides/market-data)
* [Справочник API — POST /v1/orders](/api-reference/post-orders)
* [Справочник API — GET /v1/listings](/api-reference/get-listings)