Activator — активація адреси

Активуйте адресу TRON, яка ще ніколи не використовувалася в мережі (on-chain). Абсолютно нова адреса не має запису акаунта, тому вона не може отримувати делеговану 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.

Замовлення Energy для нової адреси

Ендпоінт 1-годинної Energy самостійно активує неактивного одержувача в межах замовлення, і вартість активації додається до цього замовлення. Викликайте активатор явно, якщо вам потрібно, щоб адреса була активною до будь-якої оренди — наприклад, щоб спочатку поповнити 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 означає, що кошти не списано і жодна адреса не була активована: запит можна безпечно повторити.

Ліміти запитів (Rate Limits)

Обмеження діють для кожної IP-адреси відправника:

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

Перевищення ліміту запитів (429)

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

Примітки

• Ідемпотентність лежить на вас. Ендпоінт не має ключа ідемпотентності. Повторний запит для адреси, яка вже активна, є безпечним і безкоштовним (2001), але два одночасних запити для однієї й тієї ж абсолютно нової адреси можуть виконатися обидва. Серіалізуйте процес активації для кожної адреси на своєму боці.
• Формат orderId — A + цифри, і він є унікальним для всіх активацій.
• Наразі вебхуки для активації не надсилаються — підтвердженням є відповідь та hash. Вебхуки наразі покривають лише підтверджені делегування Energy, див. Вебхуки.