POST /apiv2/time/add

Додавання TRON-адреси до Host Mode та, за бажанням, реєстрація callback-URL для сповіщень про делегування та призупинення.

URL кінцевої точки

POST https://netts.io/apiv2/time/add

Автентифікація

Вкажіть ваш API-ключ у тілі запиту (api_key) або в заголовку X-API-KEY. IP-адреса запиту повинна бути у білому списку, налаштованому для вашого API-ключа.

Тіло запиту

json

{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",
    "infinity": true
}

Параметри

Параметр	Тип	Обов'язковий	Опис
api_key	string	Так*	API-ключ. Також може бути переданий у заголовку `X-API-KEY`.
address	string	Так	Адреса TRON (TRC-20), має відповідати `^T[1-9A-HJ-NP-Za-km-z]{33}$` (починається з `T`, 34 символи).
callback_url	string	Ні	Публічний HTTP/HTTPS URL для сповіщень про делегування Energy на адресу та про вимкнення Host Mode для адреси. Максимум 2048 символів.
infinity	boolean	Ні	`true` — також одразу перевести адресу в infinity mode, що позбавляє необхідності окремого виклику `/apiv2/time/infinitystart`. За замовчуванням `false`.

* Обов'язковий у тілі запиту, якщо не використовується заголовок X-API-KEY.

Валідація callback_url: має бути http/https, лише публічний хост (localhost, приватні діапазони RFC1918, link-local 169.254.0.0/16, приватні/link-local IPv6, зарезервовані та multicast-адреси відхиляються) і не більше 2048 символів.

Поведінка

Якщо адреса нова, вона додається до Host Mode зі статусом inactive (status = 0, cycle_set = 0). Активуйте її пізніше за допомогою /apiv2/time/order або /apiv2/time/infinitystart.
Якщо адреса вже існує у вашому обліковому записі, виклик оновлює її callback-URL.
Якщо передано callback_url, він зберігається (або оновлюється) для цієї адреси.

infinity

З "infinity": true адреса додається та активується в infinity mode за один виклик — такий самий результат, як виклик /apiv2/time/add, а потім /apiv2/time/infinitystart. Тарифікація ідентична окремому виклику: у цей момент нічого не списується, а цикли оплачуються один за одним у міру делегування Energy. Дивіться Host Mode → Cycles and Pricing.

Додавання адреси та її увімкнення — це два окремих кроки, і лише перший із них гарантований. Відповідь повідомляє результат додавання. Якщо адресу було додано, але не вдалося увімкнути, виклик все одно повертає code: 0 зі звичайним повідомленням — адреса просто залишається неактивною, точно так само, ніби ви не передавали цей прапорець. Увімкнення пропускається, коли:

ваш баланс не покриває один цикл за поточною ціною;
адреса вже активна;
адреса вже має відкрите замовлення.

Відповідь однакова як із цим прапорцем, так і без нього — жодних додаткових полів, додаткових кодів помилок, і вона не повідомляє, чи було фактично увімкнено infinity mode. Підтвердьте це за допомогою Time Status: адреса повертає status: "active" та mode: "infinity", а ідентифікатор замовлення присутній у цій відповіді. Не розглядайте code: 0 від цього ендпоінта як доказ того, що режим запущено.

Приклади запитів

cURL

bash

curl -X POST https://netts.io/apiv2/time/add \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/time/add"
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",  # optional
    # "infinity": True,  # optional: also switch the address into infinity mode
}

resp = requests.post(url, json=data, timeout=30)
result = resp.json()

if result["code"] == 0:
    print("Added:", result["data"]["address"])
else:
    print("Error:", result["msg"])

Node.js

javascript

const axios = require('axios');

const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    // callback_url: 'https://your-server.com/webhook', // optional
    // infinity: true, // optional: also switch the address into infinity mode
};

axios.post('https://netts.io/apiv2/time/add', data)
    .then(({ data: result }) => {
        if (result.code === 0) console.log('Added:', result.data.address);
        else console.error('Error:', result.msg);
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

Відповідь

Успішно (нова адреса)

json

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://your-server.com/webhook",
        "timestamp": "2026-07-13T05:30:15.123456"
    }
}

Успішно (callback-URL оновлено для існуючої адреси)

json

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2026-07-13T05:35:20.789012"
    }
}

Поля відповіді

Поле	Тип	Опис
code	integer	`0` = успіх, від'ємне число = помилка
msg	string	Зрозуміле для людини повідомлення
data.address	string	Адреса, яку було додано/оновлено
data.callback_url	string \| null	Зареєстрований callback-URL (`null`, якщо немає)
data.timestamp	string	Часова мітка операції у форматі ISO

Відповіді з помилками

Усі помилки використовують code = -1 та описують проблему в msg:

msg	Причина
`API key required in X-API-KEY header or request body`	API-ключ не надано
`Invalid API key or IP not in whitelist`	Автентифікація не вдалася
`Invalid TRC-20 address format`	Адреса не відповідає необхідному формату
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	Callback-URL відхилено валідацією
`Address belongs to another user`	Адреса зареєстрована під іншим обліковим записом
`Database error adding/updating address`	Тимчасова помилка на стороні сервера — повторіть спробу
`Internal server error`	Неочікувана помилка — повторіть спробу або зверніться до служби підтримки

json

{ "code": -1, "msg": "Invalid API key or IP not in whitelist", "data": null }

HTTP-коди стану

Помилки ендпоінта повертаються з HTTP 200 та від'ємним значенням code — перевіряйте code, а не статус HTTP. Тіло помилок завжди містить "data": null.

Деякі помилки повертаються до того, як запит досягне ендпоінта. Вони використовують статус, відмінний від 200, та іншу структуру тіла:

HTTP	Тіло	Причина
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	Баланс облікового запису занадто низький
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	API-ключ заблоковано — зверніться до служби підтримки
422	`{"detail": [ … ]}`	Тіло запиту не пройшло валідацію: обов'язкове поле відсутнє або має неправильний тип. Зверніть увагу, що поле `code` у цій відповіді відсутнє

Адреса призначення заборонена (403)

Адреса перевіряється перед її додаванням. Якщо делегування ресурсів на неї не дозволено, запит відхиляється з HTTP 403 і нічого не записується — адреса не додається і не вмикається. Тіло використовує формат detail:

code	msg	Значення
1006	`Address is blocked. Contact support.`	Адресу заблоковано
1007	`Energy rental to smart contracts is not supported.`	Адреса є смартконтрактом (адреси гаманців GasFree також є смартконтрактами)
1010	`Resource delegation to this address is not available.`	Делегування ресурсів на цю адресу недоступне
1011	`This address is frozen and cannot receive resource delegation.`	Адресу заморожено

json

{ "detail": { "code": 1007, "msg": "Energy rental to smart contracts is not supported." } }

Зворотні виклики (вебхуки)

Якщо ви зареєстрували callback_url, система викликає його щоразу, коли Energy делегується на адресу (тобто один раз за цикл делегування під час його обробки), і один раз щоразу, коли Host Mode для адреси вимикається — дивіться Подія призупинення Host Mode.

Формат запиту

Система надсилає HTTP-запит GET із параметрами запиту:

Цикл, породжений переказом USDT — energy_used присутній:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149936&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=142.3500&idle_cycle=0&energy_used=65k&charged=2.0000

Цикл без попереднього переказу — energy_used опущено:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149937&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=138.3500&idle_cycle=0&charged=4.0000

Параметр	Опис
address	TRON-адреса, яка отримала делегування Energy
order_id	Ідентифікатор делегування (`T` + внутрішній id делегування) — унікальний для кожного делегування
hash	Хеш транзакції делегування Energy в блокчейні
balance_after	Баланс вашого облікового запису в TRX одразу після цього списання (знімок на момент списання; він може змінитися на момент прибуття callback)
idle_cycle	`1` — це делегування було здійснено після 24 годин без переказів (повторне делегування під час простою), `0` — звичайний цикл, породжений вашим переказом або активацією
energy_used	Тарифна сітка Energy, спожитої переказом, який згенерував цей цикл: `65k` (65 000 Energy або менше → 2 TRX) або `131k` (більше 65 000 → 4 TRX). Необов'язковий — ключ повністю відсутній у рядку запиту (не надсилається порожнім), коли не було попереднього переказу для вимірювання: перше делегування активації, кожне повторне делегування під час простою та адреса без історії споживання. Усі вони тарифікуються за ставкою 4 TRX
charged	Сума в TRX, списана за цей цикл — `2.0000` або `4.0000`, відповідно до тарифу в `energy_used`. Присутня завжди, включно з випадками, коли `energy_used` опущено. Дивіться Host Mode → Cycles and Pricing

Використовуйте order_id та hash, щоб відрізнити одне делегування від іншого та для звірки з власними записами — два зворотні виклики для однієї адреси відрізняються цими значеннями. Використовуйте charged для відстеження витрат за цикл без опитування /apiv2/time/status, а energy_used — щоб побачити, до якого тарифу потрапив попередній переказ. Обробляйте energy_used як необов'язковий параметр — відсутність ключа означає «немає переказу для вимірювання», а не помилку, і ніколи не застосовуйте для нього значення за замовчуванням.

Подія призупинення Host Mode

Той самий callback_url викликається, коли Host Mode для адреси вимикається (стає неактивним), незалежно від причини:

GET https://your-server.com/webhook?event=host_paused&address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&reason=idle&paused_at=2026-09-13T11:16:58Z&balance=418.0000

Параметр	Опис
event	Завжди `host_paused` для цього сповіщення
address	TRON-адреса, чий Host Mode було вимкнено
reason	Чому режим було вимкнено — дивіться таблицю нижче
paused_at	Коли режим було вимкнено, ISO-8601 UTC
balance	Баланс вашого облікового запису в TRX на той момент, 4 знаки після коми

reason	Значення
`idle`	2 дні простою поспіль — два 24-годинні цикли завершилися без переказів (дивіться Host Mode → Idle shutdown)
`cycles_exhausted`	Усі замовлені цикли використано
`no_balance`	Вашого балансу було недостатньо для оплати циклу або щоденного мінімального поповнення
`stopped`	Режим було зупинено за допомогою `/apiv2/time/stop` або вимкнено з будь-якої іншої причини

Як розрізнити два сповіщення: тільки сповіщення про призупинення містить параметр event; тільки сповіщення про делегування містить order_id та hash. Формат сповіщення про делегування не змінюється.

Після призупинення адреса залишається в Host Mode зі своїм callback-URL; увімкніть її знову за допомогою /apiv2/time/order або /apiv2/time/infinitystart. Доставка працює так само, як і для сповіщень про делегування.

Приклад обробника (Python / Flask)

python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['GET'])
def energy_delegation_webhook():
    address = request.args.get('address')
    order_id = request.args.get('order_id')
    tx_hash = request.args.get('hash')
    charged = request.args.get('charged')          # TRX charged for this cycle
    energy_used = request.args.get('energy_used')  # '65k' | '131k' | None (key may be absent)

    if not address:
        return jsonify({"error": "Missing address parameter"}), 400

    if request.args.get('event') == 'host_paused':
        # Host Mode switched off: reason = idle | cycles_exhausted | no_balance | stopped
        print(f"Host Mode paused: address={address} reason={request.args.get('reason')} "
              f"paused_at={request.args.get('paused_at')} balance={request.args.get('balance')}")
        return jsonify({"status": "success"}), 200

    # Your business logic (idempotent by order_id / hash)
    print(f"Energy delegated: address={address} order_id={order_id} hash={tx_hash} "
          f"charged={charged} energy_used={energy_used}")
    return jsonify({"status": "success"}), 200

Поведінка доставки

Метод: GET, таймаут ~10 секунд. Поверніть HTTP 200 для підтвердження.
Повторні спроби: у разі невдалого запиту виконується до 3 спроб; якщо всі вони безуспішні, callback скидається (делегування Energy все одно відбувається незалежно від цього).
Без підпису: запит не підписується Netts. Секретним ключем (за наявності) є все, що ви вбудували у ваш власний callback_url.
Звірка: оскільки зворотні виклики можуть бути пропущені, також опитуйте /apiv2/time/status та забезпечте ідемпотентність вашого обробника.

Оновлення / видалення callback

Оновлення: викличте /apiv2/time/add знову з тією ж адресою та новим callback_url.
Видалення: викличте /apiv2/time/delete, щоб видалити адресу (це також видалить її callback); за потреби додайте знову без callback_url.

Пов'язані ендпоінти

POST /apiv2/time/order — купівля циклів (активує адресу)
POST /apiv2/time/infinitystart — увімкнення infinity mode
POST /apiv2/time/status — перевірка статусу та циклів
POST /apiv2/time/stop — зупинка Host Mode
POST /apiv2/time/delete — видалення адреси

Примітки

Нові адреси починають як inactive; активуйте їх за допомогою замовлення, запуску infinity або передавши тут "infinity": true.
Одна й та сама адреса не може бути зареєстрована під двома різними обліковими записами.
Перед додаванням адреса має бути активована в мережі TRON.
Смартконтракти — включно з адресами гаманців GasFree — не можуть бути додані (HTTP 403, code 1007).

POST /apiv2/time/add ​

URL кінцевої точки ​

Автентифікація ​

Тіло запиту ​

Параметри ​

Поведінка ​

infinity ​

Приклади запитів ​

cURL ​

Python ​

Node.js ​

Відповідь ​

Успішно (нова адреса) ​

Успішно (callback-URL оновлено для існуючої адреси) ​

Поля відповіді ​

Відповіді з помилками ​

HTTP-коди стану ​

Адреса призначення заборонена (403) ​

Зворотні виклики (вебхуки) ​

Формат запиту ​

Подія призупинення Host Mode ​

Приклад обробника (Python / Flask) ​

Поведінка доставки ​

Оновлення / видалення callback ​

Пов'язані ендпоінти ​

Примітки ​

POST /apiv2/time/add

URL кінцевої точки

Автентифікація

Тіло запиту

Параметри

Поведінка

infinity

Приклади запитів

cURL

Python

Node.js

Відповідь

Успішно (нова адреса)

Успішно (callback-URL оновлено для існуючої адреси)

Поля відповіді

Відповіді з помилками

HTTP-коди стану

Адреса призначення заборонена (403)

Зворотні виклики (вебхуки)

Формат запиту

Подія призупинення Host Mode

Приклад обробника (Python / Flask)

Поведінка доставки

Оновлення / видалення callback

Пов'язані ендпоінти

Примітки