API

Подробности

mode — live или test. Проверяйте его при старте: ключ, попавший не в тот конфиг, молчит ровно до момента, когда заказ либо не придёт, либо потратит настоящие деньги.

Подробности

cost_* — сколько платите нам вы; розничную цену для своего покупателя ставите у себя. Пагинация идёт по has_more, а не по общему числу: считать точное количество на каждый запрос — лишняя нагрузка, а листать вперёд это не мешает. include=offers вкладывает номиналы прямо сюда — это ровно те же строки и те же цены, что отдаёт /catalog/{id}, читаются одним запросом на всю страницу вместо запроса на каждый товар. Витрине на 50 товаров это экономит 50 обращений. Учтите, что ответ становится заметно больше: если нужен только список названий и вилка цен, не просите.

Подробности

cost — сколько вы платите нам. Розничную цену вы ставите у себя: поля price_* и price из каталога убраны 15.09.2026 вместе с настройкой наценки в кабинете — она всё равно ни на что у нас не влияла, а два места для одного числа расходились. stock: null означает, что поставщик не считает остаток по этой позиции — это не ноль. min_qty и max_qty — пределы поставщика на quantity; null значит «без ограничения», выход за них отвергается до списания денег. У пополнений (topups) quantity всегда равен 1 независимо от этих полей: количество задаётся выбором номинала. fields — что спросить у покупателя перед заказом. Все перечисленные обязательны. Ключи задаёт поставщик и они различаются от игры к игре — у 8 Ball Pool это user_id, у Age of Empire Mobile player_id плюс server_id, у AFK Journey account_id, — поэтому читайте их отсюда, а не зашивайте. Именно эти ключи уходят в объект fields при покупке; пустой список означает, что спрашивать нечего. У каждого поля есть type: "text" — свободный ввод, "select" — закрытый список, и тогда рядом лежит непустой options, а значение обязано быть ровно одним из options[].value (сервер поставщика отвергнет любое другое уже после списания). Поля type и options добавлены 15.09.2026; старые интеграции их просто не читают, ключи и label не менялись.

Подробности

available — то, что реально можно потратить прямо сейчас: сравнивайте цену с ним, а не с balance. Обычно это одно и то же число, но если мы открыли вам овердрафт, overdraft показывает разрешённый минус, а balance после его использования становится отрицательным — это не ошибка ответа. Овердрафт по умолчанию нулевой, включается только по договорённости. Исключение — Telegram-подарки: овердрафта у них нет, и цену подарка сравнивайте с balance. order_id — заказ, за который списали: по нему можно найти заказ, ответ на создание которого до вас не дошёл. У пополнений и корректировок он null.

Подробности

telegram_gift — Telegram-подарки: цены здесь нет, у каждого лота она своя (GET /gifts/{slug}). available у подарков значит только, что они подключены: этот метод к сервису подарков не ходит и его не ждёт. Открыты ли продажи прямо сейчас, говорит available в карточке лота и в котировке; если закрыты — заказ ответит 503 gifts_unavailable, ничего не списав. Подробно — в разделе «Telegram Gifts». usd_rub — курс для вашей рублёвой витрины, тот же, что отдаёт GET /rates. Он НЕ равен currencies[].rate у steam_topup и не должен им подменяться: тот курс — делитель, которым сумма в рублях превращается в номинал, и счёт считается по нему. Границы Steam заданы в долларах номинала и пересчитаны по курсу поставщика на момент ответа. min округлён вверх, max вниз, так что значение, взятое отсюда, гарантированно пройдёт проверку. Кэшируйте на минуту — в ответе это поле cache_seconds, и то же самое приходит заголовком Cache-Control: private, max-age=60. Чаще незачем: курсы у поставщика мы перечитываем раз в две минуты (rates_refresh_seconds), так что минутный кэш не сделает вас устаревшее нас. Лимит метода — 120 запросов в минуту на ключ, отдельный от лимита /quote. limit_scope: order — тысяча долларов это предел на один заказ; ограничений на сутки нет, потолком служит баланс. available: false у steam_topup означает, что поставщик или его курсы сейчас недоступны — заказы по нему не примутся.

Подробности

Это НЕ тот курс, что лежит в /products → steam_topup → currencies[].rate. Тот — делитель, которым сумма в рублях превращается в долларовый номинал, и счёт за пополнение Steam считается именно по нему: возьмёте для номинала этот курс — и посчитанная вами сумма разойдётся с нашей, а значения у краёв диапазона будут отклонены. Здесь — курс для витрины: по нему считайте свою розницу, он учитывает стоимость конвертации рублей в доллары. Кэшируйте на минуту (cache_seconds, тот же Cache-Control: private, max-age=60), лимит общий с чтением — 120 запросов в минуту. То же число дублируется в /products полем usd_rub, чтобы не делать второй запрос, если вы и так туда ходите.

Подробности

Три поля, три разных вопроса. found — нашли ли человека; can_receive — можно ли выдать ему именно это; reason — что это значит для получателя; resolution — что ответил источник в этой попытке. Решение о продаже принимайте по can_receive, карточку рисуйте по found, текст покупателю пишите по reason, а resolution берите только в логи. reason: found; has_premium — Premium у него уже есть; not_resolvable — за этим ником никого не удалось получить; unavailable — отказ по другой причине; unknown — источник не ответил, found и can_receive придут null, заказ создавать можно. Мы НЕ отдаём «такого пользователя нет» и не будем: снаружи отсутствующий аккаунт и аккаунт, который Fragment не отдаёт, — это один и тот же ответ, и @durov тому пример. resolution: fragment_ok — ник разрешён; fragment_said_no — Fragment заявил, что такого ника нет (иногда ошибочно); fragment_declined — отказал без объяснения; fragment_silent — не ответил. Для steam_topup — supplier_ok / supplier_said_no / supplier_silent. Для Steam передавайте product: steam_topup и steam_login вместо username; reason там cannot_refill, если Steam не примет пополнение. Показывайте имя и аватар покупателю до оплаты: это снимает большую часть ошибок в username. photo — прямая ссылка на CDN Telegram, она может смениться, не кэшируйте её надолго. Ответ кэшируется у нас на минуту. Лимит общий с /quote — 60 запросов в минуту.

Подробности

estimate: true бывает только у Premium: цену за конкретного получателя называет Fragment, и когда её получить не удалось — имя не передали или Fragment не ответил — в ответе стоит наша сохранённая база, то есть ориентир, а не обещание. Передавайте username: тогда при estimate: false цена ровно та, что спишется при заказе, в ответе появляется recipient с именем и аватаром получателя, а если подарить нельзя — придёт 422 recipient_refused с причиной и с тем же recipient внутри объекта error, ещё до того как вы возьмёте деньги с покупателя. Отдельный запрос к POST /recipient при этом не нужен: у Premium имя и аватар приходят вместе с ценой, у звёзд — одним кэшируемым запросом. Лимит у метода свой: 60 запросов в минуту, отдельно от лимита заказов.

Подробности

Обязательно передавайте client_ref. Если запрос отвалится по таймауту, повтор с тем же значением вернёт тот же заказ и не купит второй раз — ответ будет 200 вместо 201.

Подробности

Логин, а не отображаемое имя: деньги уходят на тот аккаунт, который назвали, и вернуть их нельзя. client_ref обязателен.

Подробности

Коды выданных товаров в списке НЕ приходят — как и данные покупателя из fields. Нашли нужный заказ, забрали коды через GET /orders/{id}: так один утёкший ключ не выгружает всю историю кодов одним запросом. has_more — это не общее число: при активной торговле страницы съезжают, поэтому для сверки надёжнее сужать created_from и created_to, чем листать вглубь. Заказы Telegram-подарков приходят здесь же, с product: telegram_gift и блоком gift, и фильтр status работает для них так же.

Подробности

delivery появляется только у товаров каталога и только когда status = delivered: до выдачи там null, а не пустой список. В items столько кодов, сколько прислал поставщик — обычно по одному на единицу quantity, но сверяйте с длиной массива, а не считайте по quantity. У пополнений (topups) кодов нет вовсе, там items пустой: товар ушёл прямо на игровой аккаунт из fields. Для звёзд, Premium и Steam полей item, fields и delivery нет — это не каталог. У Telegram-подарка вместо них блок gift с этапом покупки — см. «Ход покупки» в разделе «Telegram Gifts».

Подробности

count — сколько подарков в коллекции, по данным Fragment. image — картинка коллекции с Fragment, бывает null. Список меняется редко: кэшируйте на десять минут — cache_seconds, и то же в заголовке Cache-Control: private, max-age=600. Лимит — 20 запросов в минуту на аккаунт; сверх него ответ приходит из того, что уже прочитано.

Подробности

count — сколько подарков коллекции с этим значением, от других фильтров не зависит. image — картинка с Fragment, бывает null. Коллекции нет или мы её не продаём — 404 not_found. Эти списки почти не меняются: кэшируйте на час (cache_seconds, Cache-Control: private, max-age=3600). Лимит — 20 запросов в минуту на аккаунт; сверх — из уже прочитанного.

Подробности

price_estimate — ориентир в долларах, а не цена: он считается по цене, которую показывает Fragment, и обычно выше точной. Точную называют GET /gifts/{slug} и POST /quote. Посчитать не из чего — null. Пагинация по offset, а не по page, как у каталога: так листает сам Fragment. Страница — один его шаг, из которого мы убрали всё, что купить нельзя, поэтому она бывает короче и даже пустой при has_more: true. Пустая страница — не конец: листайте по next_offset, пока has_more не станет false, а next_offset — null. sort=ending — 400: эта сортировка про аукционы, а их в ленте нет. Фильтр без collection, слишком много значений или слишком длинное — тоже 400; коллекции нет или мы её не продаём — 404 not_found. Лента у нас в кеше около минуты. Лимит — 30 запросов в минуту на аккаунт; сверх — из уже прочитанного, и 429 rate_limited, только если отдать нечего.

Подробности

buyable: false — лот сейчас не купить, причина кодом в reason: not_for_sale — продан или снят с продажи; in_telegram — подарок сейчас в Telegram, а не на продаже; collection_not_supported — коллекцию мы не продаём. buyable: null — цену сейчас прочитать не удалось: reason тогда rate_limited (лимит аккаунта, а в кеше цены нет) или gifts_unavailable, и price, available и reserved тоже null. Карточка при этом приходит — рассмотреть подарок можно и без цены. price — точная цена для вас сейчас, у нас она держится около 30 секунд; заказ читает лот заново. available: false — заказы на этот лот сейчас не принимаются: цену показать можно, заказ получит 503 gifts_unavailable. available: null — не знаем: сверх лимита карточка собрана из уже прочитанного, а свежего ответа о продажах по этому лоту у нас нет; заказ проверит сам. reserved: null — лот свободен; {mine: true, order} — его уже покупает ваш заказ; {mine: false} — чужой. Пока reserved не null, новый заказ на лот получит 409 gift_reserved, даже при buyable: true; когда тот заказ подарок уже купил, приходит buyable: false без цены — лот ждёт передачи по нему. rarity_pct — сколько процентов подарков коллекции с тем же значением; issued — номер выпуска и тираж; address — адрес NFT; links.telegram — где подарок видно в Telegram. Чего о подарке сейчас не знаем, то приходит null. Такого подарка нет — 404 not_found. Тестовым ключом цена настоящая, а reserved всегда null и available — true: так лот увидит тестовый заказ. Лимит — 12 запросов в минуту на аккаунт; сверх — из уже прочитанного.

Подробности

Поля те же, что у звёзд, — и правило то же: продавайте по can_receive, карточку рисуйте по found, resolution — только в логи. reason: found — примет; not_resolvable — за этим ником никого не удалось получить; unavailable — аккаунт есть, но подарок не примет, например закрыл подарки в настройках приватности; unknown — Fragment не ответил, found и can_receive придут null. Ответ держится у нас минуту, и заказ в эту минуту не ищет получателя заново — поэтому проверяйте перед оплатой, а не на каждое нажатие клавиши. Неверный формат username — 400 bad_request. Лимит — 8 проверок в минуту на аккаунт, в него же идёт username в POST /quote; сверх — ответ только из кеша, а если там пусто — 429 rate_limited с Retry-After: 60.

Подробности

enough — хватает ли balance, без овердрафта: у подарков его нет. Лот, который купить нельзя, — не ответ, а 409 gift_not_buyable с кодом в reason (те же коды, что в карточке), поэтому в ответе 200 buyable — true, а reason — null, кроме одного случая ниже. Лот под заказом и закрытые продажи — не отказ, а поля, как в карточке, и заказ на такой лот не пройдёт. reserved не null — по лоту идёт заказ ({mine: true, order} — ваш, следите за ним), новый получит 409 gift_reserved; пока тот заказ подарок не купил, цена приходит как обычно, а после покупки — buyable: false, reason, price: null и enough: false. available: false — продажи на этот лот закрыты; null — котировка собрана из уже прочитанного (сверх лимита), а свежего ответа о продажах нет. kind — то же значение под тем именем, которым /quote называет товар у звёзд и Premium. С username получатель проверяется так же, как в POST /recipient: не примет — 422 recipient_refused с reason (not_resolvable или unavailable) и recipient внутри error; с боевым ключом name и photo в нём всегда null — Fragment не называет того, кто подарок не примет. Имя и аватар там бывают только в песочнице, у gs_sandbox_nogifts: не стройте на них экран. Fragment не ответил — recipient: null, а цена приходит. Без username поля recipient нет. Слаг не того вида — 400 bad_request, такого подарка нет — 404 not_found, подарки временно недоступны — 503 gifts_unavailable. Лимит — 10 котировок в минуту на аккаунт; сверх — цена из уже прочитанного, пусто — 429 rate_limited с Retry-After: 60. Тестовым ключом: цена настоящего лота, balance — игровой, reserved всегда null, available — true, и в ответе sandbox: true.

Подробности

Всё проверяется до списания: бронь лота, получатель, лот, ваш потолок и баланс. Лот читается заново, мимо кеша; ответ о получателе — тот же, что у POST /recipient, не старше минуты. 201 — заказ создан и оплачен; 200 — повтор с тем же client_ref и тем же лотом, вернулся прежний заказ и ничего не списано — так же, если повтор пришёл, пока первый запрос ещё шёл. Тот же client_ref на заказе другого вида (звёзды, Premium, Steam, каталог) или на подарке с другим лотом — 409 client_ref_conflict. Отказы, которые стоит обработать: 409 price_changed — лот дороже max_price, новая цена в поле price (покажите её покупателю и повторите с новым потолком); 409 gift_not_buyable — лот купили или сняли, код в reason; 409 gift_reserved — по лоту идёт заказ, и так до его конца, в том числе когда подарок уже куплен и ждёт передачи: mine: true и номер в order — это ваш заказ, следите за ним; mine: false — чужой; 422 recipient_refused — reason not_resolvable или unavailable и recipient внутри error (с боевым ключом name и photo в нём null); 402 insufficient_funds — balance меньше цены, overdraft в нём 0; 429 recipient_daily_limit — суточный лимит на получателя; 503 gifts_unavailable — подарки временно не принимаются, в том числе когда Fragment не ответил о получателе. Заказ ходит к Fragment за лотом, а бывает, и за получателем, и это может занять до минуты: таймаут на своей стороне ставьте не меньше 60 секунд, а после обрыва повторяйте с тем же client_ref. Лимит — 6 заказов-подарков в минуту на аккаунт сверх общего лимита заказов; сверх — 429 rate_limited с Retry-After: 60.

Подробности

gift.stage: paid — оплачен и ждёт очереди; buying — покупаем; bought — куплен, ждёт передачи; sending — передаём получателю; delivered — у получателя, status: delivered; failed — не вышло, status: failed. Всё до delivered и failed — status: processing. needs_action не null, только когда передача остановлена и ждёт решения: reason — текст для человека; can_change_recipient: true — дело в получателе, назовите другого через POST /orders/{id}/recipient; false — задержка на нашей стороне, делать ничего не нужно. Подарок в это время уже куплен, и деньги сами не возвращаются. У failed в error написано, вернулись ли деньги, а gift.refunded: true значит, что возврат уже на балансе; false при failed — он в пути и придёт в течение нескольких минут. link — где подарок видно в Telegram, recipient_name — имя получателя, как его назвал Fragment. quantity у подарка всегда 1.

Подробности

Только пока у заказа gift.needs_action.can_change_recipient: true. В остальное время — 409 bad_state: передача не остановлена из-за получателя (идёт сама или ещё не начиналась — вмешательство только сбило бы её), заказ уже закрыт (delivered или failed) или только что изменился. Перечитайте GET /orders/{id} и решайте по нему. Чужой заказ, не подарок или заказ другого режима — 404 not_found. Новый получатель не примет — 422 recipient_refused с reason; упёрся в суточный лимит — 429 recipient_daily_limit; неверный формат username — 400 bad_request; Fragment не ответил — 503 gifts_unavailable, повторите позже. После смены передача продолжается сама — следите за заказом как обычно. Лимит — 5 вызовов в минуту на аккаунт; сверх — 429 rate_limited с Retry-After: 60. То же самое можно сделать в кабинете, на странице подарка.