Time Status API

Отримання інформації про статус адрес у Host Mode — для всіх адрес вашого акаунта або для однієї адреси.

Доступні два ендпоінти:

POST /apiv2/time/status — статус для всіх ваших адрес (з опціональною пагінацією та підсумковою інформацією на рівні акаунта).
GET /apiv2/time/status/{address} — статус для однієї конкретної адреси.

POST /apiv2/time/status

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

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

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

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

Тіло запиту

json

{
    "api_key": "your_api_key",
    "page": 1,
    "page_size": 50
}

Parameter	Type	Required	Description
api_key	string	Так	API-ключ (або заголовок `X-API-KEY`).
page	integer	Ні	Номер сторінки, ≥ 1. Потребує наявності `page_size`.
page_size	integer	Ні	Кількість адрес на сторінку, 1–100. Потребує наявності `page`.

Пагінація: якщо вказано обидва параметри — page і page_size, результати пагінуються, і повертається об'єкт pagination. Без них повертаються всі адреси (до 1000), відсортовані за часом створення (спочатку новіші).

Приклади

cURL (усі адреси):

bash

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_API_KEY_HERE" }'

cURL (з пагінацією):

bash

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_API_KEY_HERE", "page": 1, "page_size": 50 }'

Python:

python

import requests

resp = requests.post(
    "https://netts.io/apiv2/time/status",
    json={"api_key": "YOUR_API_KEY_HERE"},  # add "page"/"page_size" to paginate
    timeout=30,
)
result = resp.json()

if result["code"] == 0:
    for a in result["data"]["addresses"]:
        # cycles_remaining is None in infinity mode — no limit to count down
        left = "unlimited" if a["cycles_remaining"] is None else f"{a['cycles_remaining']} left"
        print(a["address"], a["mode"], a["status"], left,
              f"spent {a['total_spent']} TRX")
else:
    print("Error:", result["msg"])

Node.js:

javascript

const axios = require('axios');

axios.post('https://netts.io/apiv2/time/status', { api_key: 'YOUR_API_KEY_HERE' })
    .then(({ data: result }) => {
        if (result.code === 0) {
            result.data.addresses.forEach(a => {
                // cycles_remaining is null in infinity mode — no limit to count down
                const left = a.cycles_remaining === null ? 'unlimited' : `${a.cycles_remaining} left`;
                console.log(a.address, a.mode, a.status, left, `spent ${a.total_spent} TRX`);
            });
        } else {
            console.error('Error:', result.msg);
        }
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

Відповідь

json

{
    "code": 0,
    "msg": "Status retrieved successfully",
    "data": {
        "summary": {
            "total_addresses": 3,
            "active_addresses": 2,
            "infinity_mode_count": 1,
            "total_cycles_ordered": 25,
            "total_open_orders": 3
        },
        "order_statistics": {
            "total_orders": 12,
            "open_orders": 3,
            "closed_orders": 9,
            "total_cycles_in_open_orders": 25,
            "total_delegations": 340,
            "total_amount_spent": 1502.4471
        },
        "addresses": [
            {
                "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                "status": "active",
                "mode": "normal",
                "cycles_ordered": 25,
                "cycle_set": 25,
                "cycles_completed": 10,
                "cycles_remaining": 15,
                "cycles_total_lifetime": 214,
                "current_cycle_no": 3,
                "open_orders": 1,
                "total_spent": 962.1184,
                "bandwidth_delegated": true,
                "created_at": "2026-07-08T12:00:00.000000",
                "updated_at": "2026-07-09T10:00:00.000000"
            },
            {
                "address": "TYn8Y3khEsLJW2ChVWFMSMeRDow6KcbMTF",
                "status": "active",
                "mode": "infinity",
                "cycles_ordered": null,
                "cycle_set": 0,
                "cycles_completed": 83,
                "cycles_remaining": null,
                "cycles_total_lifetime": 115,
                "current_cycle_no": 5,
                "open_orders": 1,
                "total_spent": 519.1234,
                "bandwidth_delegated": true,
                "created_at": "2026-07-08T08:00:00.000000",
                "updated_at": "2026-07-09T09:30:00.000000"
            }
        ],
        "timestamp": "2026-07-09T12:34:50.123456"
    }
}

З пагінацією, data також містить:

json

"pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
}

Поля summary

Поле	Опис
total_addresses	Кількість адрес у вашому акаунті
active_addresses	Адреси, які наразі активні
infinity_mode_count	Активні адреси, що працюють у infinity mode
total_cycles_ordered	Сума замовлених циклів серед відкритих замовлень (замовлення infinity виключено)
total_open_orders	Кількість відкритих замовлень для всіх адрес

Поля order_statistics

Поле	Опис
total_orders	Усі замовлення, коли-небудь створені
open_orders	Поточні відкриті замовлення
closed_orders	Закриті замовлення
total_cycles_in_open_orders	Цикли серед відкритих замовлень (infinity виключено)
total_delegations	Делегування, фактично виконані для всіх ваших адрес
total_amount_spent	Фактично списано, у TRX — сума, дійсно знята з вашого балансу

Поля об'єкта адреси

Parameter	Type	Description
address	string	TRON-адреса
status	string	`"active"` або `"inactive"`
mode	string	`"normal"`, `"infinity"` або `"off"` (якщо неактивна)
cycles_ordered	integer \| null	Замовлені цикли у відкритих замовленнях. `null` у infinity mode
cycle_set	integer	Значення `cycle_set`, збережене для адреси
cycles_completed	integer	Цикли, використані з моменту останнього запуску адреси. Скидається при зупинці режиму або закінченні замовлених циклів
cycles_remaining	integer \| null	`cycles_ordered − cycles_completed`. `null` у infinity mode
cycles_total_lifetime	integer	Усі делегування для цієї адреси за всю її історію. Ніколи не скидається
current_cycle_no	integer \| null	Порядковий номер поточного делегування з моменту останнього запуску адреси. `null`, якщо немає активного делегування
open_orders	integer	Кількість відкритих замовлень для адреси
total_spent	number	Фактично списано для цієї адреси, у TRX
bandwidth_delegated	boolean	Чи делеговано Bandwidth наразі. Bandwidth безкоштовний і входить у вартість циклу
created_at	string	ISO-мітка часу додавання
updated_at	string	ISO-мітка часу останнього оновлення

Infinity mode. Поля cycles_ordered та cycles_remaining мають значення null, а не 0 — тут немає ліміту для зворотного відліку. Сприймайте null як «безлімітно» і не трактуйте це як «не залишилося циклів». Поле cycles_completed усе одно повертає реальне число.

Три лічильники циклів, три значення. cycles_completed рахує тільки з моменту останнього запуску адреси, cycles_total_lifetime рахує за всю її історію, а current_cycle_no показує позицію поточного делегування. Вони мають відрізнятися — для однієї адреси ви можете бачити 83, 115 і 5 одночасно.

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

Усі помилки мають code = -1:

msg	Причина
`API key required in body or X-API-KEY header`	API-ключ не надано
`Invalid API key or IP not in whitelist`	Помилка автентифікації
`Page number must be >= 1`	Значення `page` менше ніж 1
`Page size must be >= 1`	Значення `page_size` менше ніж 1
`Page size must be <= 100`	Значення `page_size` більше ніж 100
`Database error getting status`	Тимчасова помилка на стороні сервера — спробуйте ще раз
`Internal server error`	Неочікувана помилка — повторіть спробу або зверніться до служби підтримки

GET /apiv2/time/status/

Статус однієї адреси.

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

GET https://netts.io/apiv2/time/status/{address}

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

Надсилайте ваш API-ключ у заголовку X-API-KEY. IP-адреса запиту має бути внесена до білого списку.

Приклади

bash

curl -X GET "https://netts.io/apiv2/time/status/TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" \
  -H "X-API-KEY: YOUR_API_KEY_HERE"

python

import requests

address = "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
resp = requests.get(
    f"https://netts.io/apiv2/time/status/{address}",
    headers={"X-API-KEY": "YOUR_API_KEY_HERE"},
    timeout=30,
)
print(resp.json())

Відповідь

json

{
    "code": 0,
    "msg": "Address status retrieved successfully",
    "data": {
        "address_info": {
            "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "status": "active",
            "mode": "normal",
            "cycles_ordered": 25,
            "cycle_set": 25,
            "cycles_completed": 10,
            "cycles_remaining": 15,
            "cycles_total_lifetime": 214,
            "current_cycle_no": 3,
            "open_orders": 1,
            "total_spent": 962.1184,
            "bandwidth_delegated": true,
            "created_at": "2026-07-08T12:00:00.000000",
            "updated_at": "2026-07-09T10:00:00.000000"
        },
        "timestamp": "2026-07-09T12:34:50.123456"
    }
}

address_info використовує ті самі поля, що й об'єкт адреси вище.

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

code = -1, наприклад:

msg	Причина
`API key required in X-API-KEY header`	Відсутній заголовок
`Invalid API key or IP not in whitelist`	Помилка автентифікації
`Address not found or doesn't belong to user`	Невідома адреса для цього акаунта
`Database error getting address status`	Тимчасова помилка на стороні сервера — спробуйте ще раз
`Internal server error`	Неочікувана помилка — повторіть спробу або зверніться до служби підтримки

Коди стану 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": [ … ]}`	Тільки POST — тіло запиту не пройшло валідацію: поле має неправильний тип, або `page`/`page_size` були надіслані без `api_key`. Зверніть увагу, що в цій відповіді немає поля `code`

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

POST /apiv2/time/add — додати адресу
POST /apiv2/time/order — купити цикли
POST /apiv2/time/infinitystart — увімкнути infinity mode
POST /apiv2/time/stop — зупинити адресу
POST /apiv2/time/delete — видалити адресу

Примітки

Ендпоінти статусу призначені лише для читання.
Повертаються лише адреси, що належать вашому акаунту.
Мітки часу є рядками у форматі ISO 8601.

Time Status API ​

POST /apiv2/time/status ​

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

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

Тіло запиту ​

Приклади ​

Відповідь ​

Поля summary ​

Поля order_statistics ​

Поля об'єкта адреси ​

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

GET /apiv2/time/status/ ​

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

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

Приклади ​

Відповідь ​

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

Коди стану HTTP ​

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

Примітки ​

Time Status API

POST /apiv2/time/status

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

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

Тіло запиту

Приклади

Відповідь

Поля summary

Поля order_statistics

Поля об'єкта адреси

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

GET /apiv2/time/status/

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

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

Приклади

Відповідь

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

Коди стану HTTP

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

Примітки