POST /apiv2/time/add

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

infinity

При "infinity": true адреса додається та активується в режимі infinity за один виклик — такий самий результат, як і при виклику /apiv2/time/add, а потім /apiv2/time/infinitystart. Тарифікація ідентична окремому виклику: на цьому етапі кошти не списуються, а цикли оплачуються один за одним під час делегування енергії. Див. 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"
    }
}

Успіх (оновлено 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`

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

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

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

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

Цикл, породжений переказом 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` + внутрішній ідентифікатор делегування) — унікальний для кожного делегування
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 — видалення адреси

Примітки

Нові адреси починають зі статусу inactive; активуйте їх за допомогою замовлення, запуску infinity або передавши тут "infinity": true.
Одна й та сама адреса не може бути зареєстрована під двома різними обліковими записами.
Адреса має бути активована в мережі TRON перед її додаванням.

POST /apiv2/time/add ​

URL ендпоінту ​

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

Тіло запиту ​

Параметри ​

Поведінка ​

infinity ​

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

cURL ​

Python ​

Node.js ​

Відповідь ​

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

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

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

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

Коди стану HTTP ​

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

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

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

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

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

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

Примітки ​

POST /apiv2/time/add

URL ендпоінту

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

Тіло запиту

Параметри

Поведінка

infinity

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

cURL

Python

Node.js

Відповідь

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

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

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

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

Коди стану HTTP

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

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

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

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

Оновлення / видалення зворотного виклику

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

Примітки