Полная выгрузка цен

Предварительная версия: метод реализован локально, но ещё не проверен как публичный сервис.

POST /v1/markets/snapshot отдаёт текущую матрицу цен из кэша в формате application/x-ndjson: одна JSON-запись на строку. Нужен scope market:read. Передавай только заголовок Authorization, без тела запроса и query-параметров.

curl --no-buffer --fail-with-body -X POST \
  -H "Authorization: Bearer $CSFOLDER_API_KEY" \
  https://api.csfolder.com/v1/markets/snapshot

Метод читает нашу БД и кэш, не запрашивая поставщика отдельно для каждого клиента. Он покрывает каталог, сохранённый в CSFolder: это не обещание, что у каждого предмета игры есть цена на каждом маркете. История — отдельный набор данных.

Как проверить завершение

Запись	Значение
start	ID запроса, версия кэша цен, время записи в кэш и верхний item ID каталога.
item	data.item_id, market_hash_name, точная phase, availability, массивы asks и bids.
end	Совпадающие ID запроса и версия, количество отправленных записей предметов.
error	Выгрузка не завершена. Частичный набор нужно отбросить; успешного end не будет.

У каждой котировки: целое amount в центах USD, currency: USD, minor_units: 2, провайдер, количество и URL. Количество и URL могут быть null. Отсутствующая запись кэша — это availability: missing и пустые массивы котировок, а не нулевая цена. Bid не подменяет ask; фаза не подменяется предметом без фазы.

Одного HTTP 200 недостаточно. Нужны ровно один start, упорядоченные записи item и один соответствующий end; проверь количество предметов. Не принимай неизвестные, лишние, повреждённые или оборванные записи. При обрыве сети строки error может не быть. Читай построчно, без response.json() и накопления всего ответа. Максимальная закодированная запись — 256 KiB.

Пиши во временный файл или промежуточную таблицу. Подменяй рабочие данные только после полной проверки завершения. При snapshot_changed или snapshot_interrupted удали частичный набор и повтори весь запрос с ограниченным backoff. Продолжения с cursor в этой версии нет. Прерванный старт может расходовать квоту — бесконечно повторять нельзя.

Согласованность и время

В успешно завершённой выгрузке цены относятся к одной версии кэша. Обновление кэша во время стриминга делает выгрузку невалидной. Идентичности предметов читаются по возрастанию item ID до зафиксированного максимума; это не снимок всей БД на один момент времени.

ingested_at — время публикации этой версии кэша в CSFolder. generated_at — начало выгрузки. Это не время наблюдения цены маркетом: текущий источник его не передаёт, поэтому price_as_of и as_of котировок остаются null. В свежей выгрузке могут быть старые исходные цены. Не превращай время выгрузки в наблюдаемую часовую точку истории, теряя это различие.

Ограничения выгрузок

Одна активная выгрузка на аккаунт, общая для всех ключей. На сервис — восемь одновременных выгрузок, дедлайн — две минуты. Медленное соединение замедляет чтение источника; при отключении клиента новые чтения прекращаются. Добавляй случайный сдвиг в расписание и соблюдай Retry-After, не запускай всех клиентов в одну секунду.

Базовые значения в разработке для стартов за скользящие 24 часа:

Тариф	Стартов
Free	Недоступно (403 до списания квоты и занятия слота)
Builder	48
Trader	144
Quant	288

Это черновые настройки доступа, не опубликованные подписки. Каждая допущенная выгрузка дополнительно расходует один месячный запрос. Отказ по слоту или суточному лимиту происходит до списания месячной единицы. Ошибка до стриминга освобождает суточную резервацию, но уже списанный месячный запрос не возвращает. После начала стриминга отмена клиентом или последующая ошибка всё равно считается стартом. При падении процесса резервация может сохраняться до истечения срока.

HTTP 429 содержит snapshot_busy, snapshot_capacity или snapshot_daily_limit и заголовок Retry-After. До отправки заголовков отсутствие данных может вернуть HTTP 503. После начала стриминга проверяй протокол завершения выше. Подробнее: лимиты и ошибки.