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

Активація адреси TRON, яка ніколи не використовувалася в мережі. Нова адреса не має запису облікового запису, тому вона не може отримувати делеговану Energy або Bandwidth, доки не буде активована. Цей ендпоінт створює обліковий запис для вас і повертає хеш транзакції активації.

Активація є одноразовою операцією для кожної адреси. Якщо адреса вже активна, ендпоінт повідомляє про це та нічого не списує.

Базовий URL ендпоінта

https://netts.io/apiv2/activator

Заголовки запиту

Заголовок	Обов'язковий	Опис
Content-Type	Так	application/json
X-API-KEY	Так	Ваш API-ключ із панелі керування Netts

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

---

Активація — POST /apiv2/activator

Тіло запиту

{ "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" }

Поле	Тип	Обов'язкове	Опис
targetAddress	рядок	Так	Адреса 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	рядок	Номер замовлення на активацію, завжди A + цифри. Використовуйте його для звірки.
targetAddress	рядок	Адреса, яку було активовано
activation_cost	число з плаваючою комою	Сума, списана з вашого балансу, у TRX
user_balance_before	число з плаваючою комою	Баланс до списання
user_balance_after	число з плаваючою комою	Баланс після списання
hash	рядок	Хеш транзакції активації. Перевірте його в будь-якому оглядачі блоків 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" \
  -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 означає, що кошти не списувалися і жодна адреса не була активована: запит можна безпечно повторити.

Ліміти запитів

Обмежено на вихідну IP-адресу:

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

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

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

Постоплатні облікові записи

Облікові записи з постоплатою використовують той самий ендпоінт, заголовки та тіло запиту. Різниця полягає в тому, як оплачується активація:

• З вашого депозиту нічого не списується. Кожна успішна активація додається до заборгованості за балансом вашого облікового запису у валюті розрахунку, узгодженій у вашому договорі. Ви оплачуєте її за рахунком-фактурою відповідно до вашої угоди.
• Ваш обліковий запис має кредитний ліміт. Поки сума заборгованості знаходиться в межах ліміту, активації приймаються навіть за нульового депозиту.
• Оплачується лише завершена активація. Вже активна адреса (2001) та невдала активація нічого не коштують.

Постоплата вмикається Netts для облікового запису за запитом. Кожна відповідь містить інформацію про те, як оплачується активація: paymentMode має значення postpaid або prepaid.

Додаткові поля запиту

Поле	Тип	Обов'язкове	Опис
test	булевий	Ні	true — лише розрахувати ціну та перевірити адресу. Нічого не активується і не тарифікується
freezePrice	булевий	Ні	true — зафіксувати ціну за вашим договором на 60 секунд. Нічого не активується і не тарифікується
quoteId	рядок	Ні	Активувати за ціною котирування, виданого через freezePrice для тієї ж адреси
priceCurrency	рядок	Ні	TRX (за замовчуванням) або валюта вашого договору, як у settlement.asset. Для постоплатних облікових записів суми у валюті вашого договору включаються завжди

quoteId не можна комбінувати з test або freezePrice. Будь-яке інше поле в тілі запиту буде відхилено.

Перевірка ціни (test: true)

{ "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH", "test": true }

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 1,
            "unitPriceSun": null,
            "discount": null,
            "energyTRX": "0.000000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "1.100000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.000000", "activation": "0.364333", "total": "0.364333"}},
            "fxAt": "2026-10-19T07:17:33.475335+00:00",
            "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH"
        }
    }
}

activationCheck: inactive — адреса потребує активації та буде оплачена; active — адреса вже активна, wouldCostTRX становить 0; unknown — не вдалося перевірити зараз.

alt.<currency> — ті самі суми у валюті вашого договору. fxAt — час використання курсу валют.

Котирування з фіксованою ціною (freezePrice: true)

1. Надішліть запит із "freezePrice": true. Відповідь містить код 10011 (Quote issued), ті самі поля, що й перевірка ціни, плюс quoteId та expiresAt.
2. Протягом 60 секунд надішліть запит із "quoteId": "<quoteId>" та тією самою targetAddress.
3. Активація тарифікується за вказаною в котируванні ціною — ціною за вашим договором на момент котирування.

Котирування можна використати один раз. Прострочене або вже використане котирування відхиляється, і нічого не активується.

Успішна активація

{
    "detail": {
        "code": 10000,
        "msg": "Address activated successfully, 1.1 TRX service cost, postpaid",
        "data": {
            "orderId": "A564125",
            "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH",
            "activation_cost": 1.1,
            "user_balance_before": 0.0,
            "user_balance_after": 0.0,
            "hash": "bd9ea6ef92ce4ba6553af3930a03abe874cdfcc2399b7fdd9abdb11570de2920",
            "paymentMode": "postpaid",
            "activationTRX": "1.100000",
            "totalTRX": "1.100000"
        }
    }
}

Поле	Опис
activation_cost	Вартість активації в TRX. Для постоплатних облікових записів вона не списується з депозиту
user_balance_before / user_balance_after	Ваш депозит — без змін для постоплатних облікових записів
paymentMode	postpaid
activationTRX / totalTRX	Точні суми, 6 знаків після коми
quoteId, alt	Присутні, коли активація була виконана з котируванням

Досягнуто кредитного ліміту (402)

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

Нічого не активується і не тарифікується. Нові активації знову прийматимуться, щойно ваш платіж буде зареєстровано або ваш ліміт буде збільшено.

Коди помилок постоплати

Код	HTTP	Опис
10010	200	Результат перевірки ціни (test)
10011	200	Котирування видано (freezePrice)
1004	402	Досягнуто кредитного ліміту постоплати
4100	400	Недійсний запит
4101	400	Непідтримувана priceCurrency
4102	400	quoteId скомбіновано з test або freezePrice
4103	409	Котирування вже використано
4104	409	Термін дії котирування закінчився
4106	404	Котирування не знайдено
4107	409	Параметри запиту відрізняються від котирування
4108	400	Недійсний формат quoteId
4109	422	Недоступно для субрахунків
5032	503	Ціна тимчасово недоступна
5033	503	Курс валют тимчасово недоступний
5034	503	Білінг тимчасово недоступний — активацію не було прийнято
5036	503	Перевірка кредиту тимчасово недоступна — повторіть спробу пізніше

Для всіх наведених вище відповідей 4xx та 503 нічого не активується і не тарифікується.

---

Примітки

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