Активатор — активация адреса

Активация адреса TRON, который никогда не использовался в сети. У совершенно нового адреса отсутствует запись аккаунта, поэтому он не может получать делегированную энергию (Energy) или пропускную способность (Bandwidth) до момента активации. Этот эндпоинт создает аккаунт для вас и возвращает хеш транзакции активации.

Активация — это однократная операция для каждого адреса. Если адрес уже активен, эндпоинт сообщит об этом и не спишет средства.

Базовый URL эндпоинта

https://netts.io/apiv2/activator

Устаревший путь https://netts.io/apiv2/activation обслуживается тем же сервисом и работает абсолютно аналогично. Для новых интеграций следует использовать /apiv2/activator.

Заголовки запроса

Заголовок	Обязательный	Описание
Content-Type	Да	application/json
X-API-KEY	Да	Ваш API-ключ из панели управления Netts
X-Real-IP	Да	IP-адрес из вашего белого списка

Ваш user_id определяется на основе API-ключа — передавать его не требуется.

---

Активировать — POST /apiv2/activator

Тело запроса

{ "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" }

Поле	Тип	Обязательное	Описание
targetAddress	string	Да	Адрес TRON для активации. Должен соответствовать ^T[A-Za-z0-9]{33}$ (34 символа, начинается с T).

Ответ — активирован (200, код 10000)

{
    "detail": {
        "code": 10000,
        "msg": "Address activated successfully, 1.1 TRX deducted",
        "data": {
            "orderId": "A123456",
            "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "activation_cost": 1.1,
            "user_balance_before": 500.00,
            "user_balance_after": 498.90,
            "hash": "0000000000000000000000000000000000000000000000000000000000000000"
        }
    }
}

Поле	Тип	Описание
orderId	string	Номер заказа на активацию, всегда A + цифры. Используйте его для сверки.
targetAddress	string	Адрес, который был активирован
activation_cost	float	Сумма, списанная с вашего баланса, в TRX
user_balance_before	float	Баланс до списания
user_balance_after	float	Баланс после списания
hash	string	Хеш транзакции активации. Проверьте его в любом обозревателе блоков TRON.

Ответ — уже активен (200, код 2001)

Возвращается, если адрес уже существует в сети. Плата не взимается.

{
    "detail": {
        "code": 2001,
        "msg": "Address is already activated",
        "data": {
            "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "status": "already_activated",
            "user_balance": 500.00,
            "activation_cost": 0,
            "activation_required": false
        }
    }
}

Проверяйте code, прежде чем предполагать списание: 10000 означает, что вы заплатили, 2001 — списания не было.

Пример

curl -X POST https://netts.io/apiv2/activator \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{"targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"}'

---

Стоимость

Пункт	Сумма
Активация	1.1 TRX
Адрес уже активен	0

Сумма фиксирована и не зависит от адреса или состояния сети. Она списывается с вашего баланса Netts в момент успешной активации — никогда заранее. Неудачная активация ничего не стоит.

Ваш баланс должен покрывать эту стоимость, иначе запрос будет отклонен с ошибкой 403 (1004), и заказ не будет создан.

---

Когда это необходимо

• Перед арендой энергии (Energy) или пропускной способности (Bandwidth) для нового адреса. Делегирование несуществующему аккаунту завершится ошибкой. Сначала активируйте, затем заказывайте.
• Перед первым входящим переводом на адрес, который вы сгенерировали самостоятельно.

Вам не нужно вызывать этот эндпоинт для адреса, который когда-либо получал TRX или токен — он уже активен, и вызов просто вернет 2001.

Заказ энергии для нового адреса

Эндпоинт 1-часовой энергии самостоятельно активирует неактивного получателя в рамках заказа, и стоимость активации добавляется к этому заказу. Вызывайте активатор явно, если хотите, чтобы адрес был активен до какой-либо аренды — например, чтобы сначала пополнить Bandwidth, для чего обязательно требуется активный аккаунт.

---

Время выполнения

Активация — это реальная транзакция в блокчейне. Эндпоинт возвращает ответ после того, как она отправлена в сеть и запись об активации создана, обычно в течение нескольких секунд.

Адрес становится пригодным для использования только после того, как транзакция будет включена в блок — примерно через ~3 секунды после ответа, так как это интервал создания блока в сети TRON. Если ваш следующий шаг зависит от активности адреса (например, заказ Bandwidth), подтвердите его статус в блокчейне по возвращенному hash, а не выполняйте вызов немедленно.

---

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

Код	Описание	HTTP-статус
10000	Адрес активирован, баланс списан	200
2001	Адрес уже активирован, списания нет	200
-1	Неверный API-ключ / IP отсутствует в белом списке	401
1004	Недостаточно средств — в сообщении указано, сколько требуется и сколько у вас есть	403
-	Неверный формат targetAddress (должен содержать 34 символа, начинаться с T)	422
5003	Сбой активации или сервис временно недоступен — повторите попытку позже	503
5000	Внутренняя ошибка сервера	500

Код 503 означает, что списания не произошло и адрес не был активирован: запрос можно безопасно повторить.

Лимиты запросов

Ограничения действуют на каждый исходный IP-адрес:

Период	Лимит
1 секунда	5 запросов
1 минута	60 запросов

Превышение лимита запросов (429)

{ "message": "API rate limit exceeded" }

Примечания

• Идемпотентность лежит на вашей стороне. У эндпоинта нет ключа идемпотентности. Повторный запрос для адреса, который уже активен, безопасен и бесплатен (2001), однако два одновременных запроса для одного и того же нового адреса могут быть обработаны оба. Обеспечьте последовательную активацию каждого адреса на своей стороне.
• Формат orderId — A + цифры, он уникален для каждой активации.
• Вебхук для активации в настоящее время не отправляется — подтверждением служат ответ и hash. Вебхуки в настоящее время охватывают только подтвержденные делегирования энергии, см. Вебхуки.