POST /apiv2/time/add

Добавить TRON-адрес в Host Mode и, при необходимости, зарегистрировать 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	Нет	Публичный URL HTTP/HTTPS для уведомлений при делегировании Energy на адрес. Максимум 2048 символов.
infinity	boolean	Нет	`true` — также сразу перевести адрес в режим infinity, избавляя от отдельного вызова `/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 со статусом неактивен (status = 0, cycle_set = 0). Активируйте его позже с помощью /apiv2/time/order или /apiv2/time/infinitystart.
Если адрес уже существует в вашем аккаунте, вызов обновляет его URL обратного вызова.
Если передан callback_url, он сохраняется (или обновляется) для этого адреса.

infinity

При "infinity": true адрес добавляется и активируется в режиме infinity за один вызов — тот же результат, что и при последовательном вызове /apiv2/time/add, а затем /apiv2/time/infinitystart. Списание средств происходит точно так же, как и при отдельном вызове: в этот момент ничего не списывается, а циклы оплачиваются по одному по мере делегирования Energy. См. Host Mode → Cycles and Pricing.

Добавление адреса и его включение — это два отдельных шага, и гарантируется только первый из них. Ответ сообщает результат добавления. Если адрес был добавлен, но его не удалось включить, вызов все равно вернет code: 0 со стандартным сообщением — адрес просто останется неактивным, точно так же, как если бы вы не передавали этот флаг. Включение пропускается, если:

вашего баланса недостаточно для покрытия одного цикла по текущей цене;
адрес уже активен;
по адресу уже есть открытый заказ.

Ответ выглядит одинаково как с флагом, так и без него — никаких дополнительных полей, никаких дополнительных кодов ошибок, и он не сообщает, был ли режим infinity фактически включен. Проверьте это с помощью 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"
    }
}

Успешное выполнение (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	Зарегистрированный 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`	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` в этом ответе отсутствует

Обратные вызовы (вебхуки)

Если вы зарегистрировали callback_url, система вызывает его каждый раз при делегировании Energy на адрес (т. е. один раз за каждый цикл делегирования по мере его обработки).

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

Система отправляет 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 сразу после этого списания (снимок на момент списания; к моменту доставки обратного вызова он может измениться)
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 как необязательный параметр — отсутствие ключа означает «нет перевода для измерения», а не ошибку, и никогда не задавайте для него значение по умолчанию.

Пример обработчика (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

    # 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 попыток; если все они завершились неудачно, обратный вызов отбрасывается (делегирование Energy при этом все равно происходит).
Без подписи: запрос не подписывается Netts. Секретом (если он есть) является то, что вы сами включили в свой callback_url.
Сверка данных: поскольку обратные вызовы могут быть пропущены, также опрашивайте /apiv2/time/status и делайте ваш обработчик идемпотентным.

Обновление / удаление обратного вызова

Обновление: вызовите /apiv2/time/add повторно с тем же адресом и новым callback_url.
Удаление: вызовите /apiv2/time/delete, чтобы удалить адрес (это также удалит его обратный вызов); при необходимости добавьте его заново без callback_url.

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

POST /apiv2/time/order — покупка циклов (активирует адрес)
POST /apiv2/time/infinitystart — включение режима infinity
POST /apiv2/time/status — проверка статуса и циклов
POST /apiv2/time/stop — остановка Host Mode
POST /apiv2/time/delete — удаление адреса

Примечания

Новые адреса создаются неактивными; активируйте их с помощью заказа, запуска режима infinity или передачи "infinity": true в этом запросе.
Один и тот же адрес не может быть зарегистрирован в двух разных аккаунтах.
Перед добавлением адрес должен быть активирован в сети TRON.

POST /apiv2/time/add ​

URL эндпоинта ​

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

Тело запроса ​

Параметры ​

Поведение ​

infinity ​

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

cURL ​

Python ​

Node.js ​

Ответ ​

Успешное выполнение (новый адрес) ​

Успешное выполнение (URL обратного вызова обновлен для существующего адреса) ​

Поля ответа ​

Ответы с ошибками ​

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

Обратные вызовы (вебхуки) ​

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

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

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

Обновление / удаление обратного вызова ​

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

Примечания ​

POST /apiv2/time/add

URL эндпоинта

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

Тело запроса

Параметры

Поведение

infinity

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

cURL

Python

Node.js

Ответ

Успешное выполнение (новый адрес)

Успешное выполнение (URL обратного вызова обновлен для существующего адреса)

Поля ответа

Ответы с ошибками

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

Обратные вызовы (вебхуки)

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

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

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

Обновление / удаление обратного вызова

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

Примечания