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 для отправки уведомлений при делегировании энергии на адрес и при отключении 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, IPv6 private/link-local, зарезервированные и мультикаст-адреса отклоняются), длина не более 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. Списание средств происходит точно так же, как и при отдельном вызове: в момент добавления ничего не списывается, а циклы оплачиваются по одному по мере делегирования энергии. См. 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." } }

Callbacks (вебхуки)

Если вы зарегистрировали callback_url, система обращается к нему каждый раз, когда на адрес делегируется энергия (т.е. один раз за каждый обработанный цикл делегирования), и один раз при каждом отключении 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-адрес, получивший делегирование энергии
order_id	Идентификатор делегирования (`T` + внутренний идентификатор делегирования) — уникален для каждого делегирования
hash	Хеш транзакции делегирования энергии в блокчейне
balance_after	Баланс вашего аккаунта в TRX сразу после этого списания (снимок на момент списания; к моменту получения callback он может измениться)
idle_cycle	`1` — данное делегирование выполнено после 24 часов отсутствия переводов (повторное холостое делегирование), `0` — обычный цикл в результате вашего перевода или активации
energy_used	Тарифный план по объему потребленной энергии для перевода, породившего этот цикл: `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 для различения одного делегирования от другого и сверки с вашими внутренними записями — два callback-уведомления для одного и того же адреса отличаются этими значениями. Используйте 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`	Вашего баланса недостаточно для оплаты цикла или пополнения daily minimum
`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 отбрасывается (делегирование энергии всё равно выполняется).
Без подписи: запрос не подписывается со стороны Netts. Секретом (при необходимости) является то, что вы самостоятельно встроили в ваш callback_url.
Сверка данных: поскольку callback-уведомления могут быть пропущены, также опрашивайте /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) ​

Callbacks (вебхуки) ​

Формат запроса ​

Событие приостановки Host Mode ​

Пример обработчика (Python / Flask) ​

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

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

Связанные эндпоинты ​

Примечания ​

POST /apiv2/time/add

URL эндпоинта

Аутентификация

Тело запроса

Параметры

Поведение

infinity

Примеры запросов

cURL

Python

Node.js

Ответ

Успех (новый адрес)

Успех (обновлен callback URL для существующего адреса)

Поля ответа

Ответы с ошибкой

Коды состояния HTTP

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

Callbacks (вебхуки)

Формат запроса

Событие приостановки Host Mode

Пример обработчика (Python / Flask)

Поведение при доставке

Обновление / удаление callback

Связанные эндпоинты

Примечания