Вопросы и ответы
То, что спрашивают до первого заказа, — по группам и коротко. Где ответ принадлежит контракту, а не нашей привычке, то же самое подробно сказано в документации API.
Энергия и цена
Что такое энергия TRON?
Ресурс сети, которым оплачивается исполнение смарт-контрактов. Если энергии на кошельке-отправителе хватает, перевод USDT почти не сжигает TRX.
Почему это дешевле сжигания?
Сжигание оценивает энергию по протокольной ставке, ~210 sun за единицу, — это число не меняется никогда. Мы закупаем делегированную энергию объёмом и продаём её за долю этой ставки; действующая прямо сейчас цена — на странице цен.
Все цены →
Что, если я не уложусь в четырёхминутное окно?
В mode A списание остаётся: энергия доставлена, а платите вы за доставку. В mode B после закрытия окна мы не отправляем ничего, поэтому позиция уходит в отказ, а резерв возвращается целиком. Окно приходит с каждым заказом — стройте свой процесс вокруг него.
Пропущенное окно отправки стоит одинаково в обоих режимах?
Нет. В mode A энергия доставлена, поэтому списание остаётся, — и в mode C тоже, где ждать нечего: перевода нет, и позиция просто истекает с закрытием окна. В mode B после закрытия окна мы не отправляем вовсе: перевод, ушедший позже, встретил бы кошелёк, с которого делегированная энергия уже снята, и сжёг бы ваш TRX. Позиция закрывается как failed с broadcast_window_missed, резерв возвращается целиком, а купленная под неё энергия — наша потеря.
Деньги и возвраты
Чем платить?
Предоплаченным балансом в TRX: отправляете TRX на свой персональный адрес и тратите их на услуги. Цены фиксируются в момент создания заказа.
Какой токен можно отправлять на депозитный адрес?
TRX, и только TRX. USDT на депозитный адрес автоматически не зачисляется: курсовой риск мы на себя не берём и обменом не занимаемся, поэтому такой перевод откладывается на разбор человеком, а зачислять его или нет — наше решение в каждом случае отдельно. Отправили не тот токен? Напишите нам и больше не отправляйте.
Через сколько депозитом можно распоряжаться?
После 3 подтверждений — примерно десять секунд. Дальше баланс показывается тремя частями: всего, зарезервировано под заказы в работе и доступно. Заказ создаётся из доступной части, а не из общей.
Заказ можно отменить?
Только до начала закупки; после неё ответ — order_not_cancelable, потому что энергия уже куплена. Отменённый заказ возвращает резерв целиком и не списывает ничего.
Как с возвратами?
Возвраты автоматические и обращения не требуют. Правило одно: за недоставленную энергию мы денег не берём, и резерв возвращается на баланс — сорвавшаяся доставка, заказ, отменённый до начала закупки, неизрасходованный остаток суток Auto-refill. Доставленная энергия оплачивается, воспользовались вы ею или нет.
Безопасность и ключи
Какие ключи вам нужны?
Никаких. Mode A вашу транзакцию вообще не видит. Mode B принимает уже подписанную вами, и изменить в ней байт мы не можем.
Вы принимаете отправителя с мультиподписью?
В mode B — нет: в транзакции должна стоять ровно одна подпись владельца, с Permission_id 0. Состав ключей мультиподписного счёта живёт в сети и меняется без нашего ведома, поэтому обещать, что отправку примут, мы не можем. В mode A о том, как вы подписываете, мы не знаем ничего — перевод отправляете вы сами.
Что вы храните и как долго?
В mode B подписанная вами транзакция лежит зашифрованной и стирается через 7 дней после того, как заказ дошёл до финального статуса. Заказы, движения по счёту и депозиты остаются: это бухгалтерия, и хранить её мы обязаны. Больше вашего здесь нет ничего — ни приватных ключей, ни сид-фраз, ни распоряжения вашими средствами.
Интеграция
Есть ли лимиты?
120 заказов в минуту на ключ, до 500 переводов в одном пакетном заказе. За пределом вы получите Retry-After, а не молчаливый отказ.
Что на самом деле означает completed?
Что энергия доставлена, а не что ваш перевод ушёл. Обязательство — доставка, на ней заказ и закрывается, поэтому в mode A completed может наступить раньше, чем вы что-то отправили. Ориентируйтесь на появление send_before в заказе, а не на слово ready: при опросе раз в две секунды ready можно не застать вовсе.
Как работает идемпотентность?
Idempotency-Key связан с сырыми байтами тела, с которым он пришёл. Тот же ключ и байт-идентичное тело возвращают тот же заказ; тот же ключ с другим телом — конфликт; запрос, отбитый валидацией, ключ не расходует, и его можно повторить тем же ключом с исправленным телом. Сериализуйте тело один раз и повторяйте ровно те же байты: другой порядок ключей или лишний пробел — это уже другое тело.
Можно проверить адрес, ничего не заплатив?
Да, и это бесплатно. GET /v1/address-check рассказывает, что мы знаем о кошельке, а POST /v1/estimate считает до 500 адресатов по тем же правилам, по которым считал бы заказ, — включая тех, кого блокирует контракт токена. Ни один из них ничего не резервирует и ничего не списывает.
Ваш счёт
Может ли кошелёк держать энергию сам?
Да — правило Auto-refill: адрес плюс суточный лимит. Энергия восполняется после каждого перевода, а лимит — жёсткий потолок на сутки.
Какой порог ставить у balance.low?
Число задаёте вы сами — balance_low_threshold_trx в PATCH /v1/settings; balance.low — событие, которое по нему приходит. Разумная величина — примерно ваш суточный оборот: тогда предупреждение придёт за сутки до того, как заказы начнут получать insufficient_balance, а не вместо первого отказа. Заметно меньше — и событие превращается в уведомление постфактум, заметно больше — в шум. Ноль выключает его.
Есть песочница или минимальный объём?
Ни минимального объёма, ни абонентской платы, ни платы за простой. Песочницы тоже нет: базовый адрес боевой, и другого не существует. Справочные эндпоинты, оценка и проба вебхука ничего не стоят, поэтому большую часть интеграции можно построить до первого заказа.