POST /apiv2/time/order

Покупка определенного количества циклов для адреса в Host Mode.

Обзор

Эндпоинт Time Order позволяет приобрести определенное количество циклов делегации энергии для TRON адреса, уже зарегистрированного в Host Mode. Каждый цикл обеспечивает одну делегацию 131,000 энергии на 24 часа.

URL эндпоинта

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

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

Этот эндпоинт использует аутентификацию через JSON тело (не заголовки). Ваш API ключ, целевой адрес и количество циклов предоставляются в теле запроса.

Заголовки запроса

Заголовок	Обязательный	Описание
Content-Type	Да	application/json

Тело запроса

json

{
    "api_key": "ваш_api_ключ",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "cycles": 2
}

Параметры

Параметр	Тип	Обязательный	Валидация	Описание
api_key	string	Да	Должен существовать в системе	Ваш API ключ для аутентификации и биллинга
address	string	Да	Формат TRC-20	TRON адрес для покупки циклов (должен быть в Host Mode)
cycles	integer	Да	>= 1	Количество циклов для покупки

Валидация параметров

api_key: Должен быть действительным API ключом с достаточным балансом
address: Должен соответствовать формату TRC-20 и уже быть добавлен в Host Mode
cycles: Должно быть положительным целым числом (минимум 1)
IP адрес: IP запроса должен быть в белом списке вашего API ключа

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

cURL

bash

curl -X POST https://netts.io/apiv2/time/order \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", 
    "cycles": 2
  }'

Python

python

import requests

url = "https://netts.io/apiv2/time/order"
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "cycles": 2
}

response = requests.post(url, json=data, verify=True)

if response.status_code == 200:
    result = response.json()
    if result['code'] == 0:
        order_data = result['data']
        print(f"✅ Заказ создан успешно:")
        print(f"  ID заказа: {order_data['order_id']}")
        print(f"  Адрес: {order_data['address']}")
        print(f"  Циклы: {order_data['cycles']}")
        print(f"  Сумма: {order_data['amount']} TRX")
        print(f"  Статус: {order_data['status']}")
    else:
        print(f"❌ Ошибка: {result['msg']}")
else:
    print(f"HTTP Ошибка: {response.status_code}")

Node.js

javascript

const axios = require('axios');

const url = 'https://netts.io/apiv2/time/order';
const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    cycles: 2
};

axios.post(url, data)
    .then(response => {
        const result = response.data;
        if (result.code === 0) {
            const order = result.data;
            console.log(`✅ Заказ создан: ID ${order.order_id}`);
            console.log(`Адрес: ${order.address}`);
            console.log(`Циклы: ${order.cycles}, Сумма: ${order.amount} TRX`);
        } else {
            console.log(`❌ Ошибка: ${result.msg}`);
        }
    })
    .catch(error => {
        console.error('Ошибка запроса:', error.response?.data || error.message);
    });

Ответ

Успешный ответ (200 OK)

json

{
    "code": 0,
    "msg": "Order created successfully",
    "data": {
        "order_id": 12345,
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "cycles": 2,
        "amount": 5.978,
        "status": "active",
        "timestamp": "2025-09-02T07:30:15.123456"
    }
}

Поля ответа

Поле	Тип	Описание
code	integer	Код ответа (0 = успех, отрицательный = ошибка)
msg	string	Человекочитаемое сообщение ответа
data.order_id	integer	Уникальный ID созданного заказа
data.address	string	TRON адрес для которого куплены циклы
data.cycles	integer	Количество купленных циклов
data.amount	number	Общая сумма заказа в TRX
data.status	string	Статус заказа ("active")
data.timestamp	string	ISO временная метка создания заказа

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

Ошибка аутентификации (401)

json

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

Неверный формат адреса (400)

json

{
    "code": -1,
    "msg": "Invalid TRC-20 address format", 
    "data": null
}

Неверное количество циклов (400)

json

{
    "code": -1,
    "msg": "Cycle count must be 1 or more",
    "data": null
}

Недостаточный баланс (402)

json

{
    "code": -1,
    "msg": "Insufficient balance for order",
    "data": null
}

Конфликт заказов (409)

json

{
    "code": -6,
    "msg": "Cannot buy cycles: There is an open order with infinity cycles for this address",
    "data": null
}

Ошибка базы данных (500)

json

{
    "code": -1,
    "msg": "Database error processing order",
    "data": null
}

Ограничения частоты запросов

Следующие ограничения применяются к этому эндпоинту (на IP адрес):

Период	Лимит	Описание
1 секунда	1 запрос	Максимум 1 запрос в секунду
1 минута	60 запросов	Максимум 60 запросов в минуту

Заголовки ограничений

API возвращает информацию об ограничениях в заголовках ответа:

http

X-RateLimit-Limit-Minute: 6
X-RateLimit-Remaining-Minute: 5
Retry-After: 10

Превышение лимита (429)

json

{
    "message": "API rate limit exceeded"
}

При превышении лимита ждите время, указанное в заголовке Retry-After.

Что происходит после заказа циклов

Проверка баланса: Система проверяет достаточность TRX баланса
Создание заказа: Создается запись заказа в netts_web_hosting_orders
Обновление режима: Обновляется cycle_set в netts_web_hosting_mode
Списание средств: TRX списываются с баланса пользователя
Активация: Адрес готов к использованию купленных циклов

Влияние на Host Mode

После покупки циклов:

Цикл лимит: Адрес получает определенное количество циклов
Автоматическое использование: Циклы расходуются при делегациях энергии
Мониторинг: Количество оставшихся циклов отслеживается системой
Истечение: При исчерпании циклов энергия перестает делегироваться

Система биллинга

Расчет стоимости

Цена за цикл: Динамическая цена из таблицы netts_time_price_public
Общая сумма: количество_циклов × цена_за_цикл
Валюта: Все цены в TRX

Проверка баланса

TG пользователи: Баланс из netts_user_api_deduction_tg
Обычные пользователи: Баланс из netts_user_api_deduction
Минимум: Должно быть достаточно средств для полного заказа

Детали безопасности

Валидация адреса

Проверка формата: Адрес должен соответствовать формату TRC-20
Проверка длины: Ровно 34 символа
Проверка существования: Адрес должен быть уже добавлен в Host Mode

Безопасность аутентификации

Валидация API ключа: Ключ должен существовать и быть активным
IP белый список: IP запроса должен быть в белом списке вашего аккаунта
Проверка пользователя: Система проверяет TG и обычных пользователей

Безопасность заказов

Проверка дубликатов: Предотвращение конфликтующих заказов
Проверка лимитов: Проверка на существующие infinity заказы
Безопасность транзакций: Использование транзакций БД для консистентности

Технические детали

Архитектура сервиса

Порт: 9011
Framework: FastAPI с Pydantic моделями
База данных: PostgreSQL с пулингом соединений
Балансировка нагрузки: HAProxy для read/write операций
Логирование: Подробное логирование в /path/to/your/logs/time_api.log

Операции с базой данных

Таблицы:
- netts_web_hosting_orders (заказы)
- netts_web_hosting_mode (режимы адресов)
- netts_time_price_public (цены)
Операция: INSERT нового заказа + UPDATE режима
Транзакции: Атомарные операции с откатом при ошибках

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

После заказа циклов вы можете:

Time Status - Проверить статус заказа и циклы
Time Infinity Start - Переключиться на unlimited режим
Time Stop - Временно приостановить делегацию энергии
Time Delete - Удалить адрес из Host Mode

Лучшие практики

Перед заказом циклов

Проверить адрес: Убедиться что адрес уже добавлен в Host Mode
Проверить баланс: Убедиться в достаточности TRX баланса
Рассчитать потребность: Оценить количество нужных циклов
Проверить существующие заказы: Убедиться в отсутствии конфликтов

После заказа циклов

Мониторить статус: Использовать Time Status для отслеживания
Отслеживать использование: Следить за расходом циклов
Планировать пополнение: Заказывать новые циклы заранее
Мониторить производительность: Отслеживать эффективность делегаций

Устранение неполадок

Частые проблемы

Проблема	Причина	Решение
Ошибка аутентификации	Неверный API ключ или IP не в белом списке	Проверить API ключ и добавить IP в белый список
Неверный формат адреса	Адрес не соответствует формату TRC-20	Проверить что адрес 34 символа начинающихся с 'T'
Недостаточный баланс	Не хватает TRX для заказа	Пополнить баланс аккаунта
Конфликт заказов	Существует активный infinity заказ	Остановить infinity режим перед заказом циклов
Адрес не найден	Адрес не добавлен в Host Mode	Использовать Time Add для добавления адреса

Справочник кодов ошибок

Код	HTTP статус	Описание	Требуемое действие
`0`	200	Успех	Нет - заказ создан успешно
`-1`	400/401/500	Различные ошибки	Проверить сообщение об ошибке
`-6`	409	Конфликт заказов	Решить конфликт с существующими заказами

Ограничения частоты запросов

Следующие ограничения применяются к этому эндпоинту (на IP адрес):

Период	Лимит	Описание
1 секунда	1 запрос	Максимум 1 запрос в секунду
1 минута	60 запросов	Максимум 60 запросов в минуту

Заголовки ограничений

API возвращает информацию об ограничениях в заголовках ответа:

http

X-RateLimit-Limit-Minute: 6
X-RateLimit-Remaining-Minute: 5
Retry-After: 10

Превышение лимита (429)

json

{
    "message": "API rate limit exceeded"
}

При превышении лимита ждите время, указанное в заголовке Retry-After.

Примечания

Цена циклов: Определяется динамически из базы данных
Биллинг: Циклы списываются с баланса аккаунта автоматически
Конфликты: Нельзя купить циклы если активен infinity режим
Мониторинг: Используйте Time Status для отслеживания использования циклов
Активация: Адрес должен быть сначала добавлен через Time Add
Лимиты: Проверьте лимиты аккаунта на максимальное количество циклов

POST /apiv2/time/order ​

Обзор ​

URL эндпоинта ​

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

Заголовки запроса ​

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

Параметры ​

Валидация параметров ​

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

cURL ​

Python ​

Node.js ​

Ответ ​

Успешный ответ (200 OK) ​

Поля ответа ​

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

Ошибка аутентификации (401) ​

Неверный формат адреса (400) ​

Неверное количество циклов (400) ​

Недостаточный баланс (402) ​

Конфликт заказов (409) ​

Ошибка базы данных (500) ​

Ограничения частоты запросов ​

Заголовки ограничений ​

Превышение лимита (429) ​

Что происходит после заказа циклов ​

Влияние на Host Mode ​

Система биллинга ​

Расчет стоимости ​

Проверка баланса ​

Детали безопасности ​

Валидация адреса ​

Безопасность аутентификации ​

Безопасность заказов ​

Технические детали ​

Архитектура сервиса ​

Операции с базой данных ​

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

Лучшие практики ​

Перед заказом циклов ​

После заказа циклов ​

Устранение неполадок ​

Частые проблемы ​

Справочник кодов ошибок ​

Ограничения частоты запросов ​

Заголовки ограничений ​

Превышение лимита (429) ​

Примечания ​

POST /apiv2/time/order

Обзор

URL эндпоинта

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

Заголовки запроса

Тело запроса

Параметры

Валидация параметров

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

cURL

Python

Node.js

Ответ

Успешный ответ (200 OK)

Поля ответа

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

Ошибка аутентификации (401)

Неверный формат адреса (400)

Неверное количество циклов (400)

Недостаточный баланс (402)

Конфликт заказов (409)

Ошибка базы данных (500)

Ограничения частоты запросов

Заголовки ограничений

Превышение лимита (429)

Что происходит после заказа циклов

Влияние на Host Mode

Система биллинга

Расчет стоимости

Проверка баланса

Детали безопасности

Валидация адреса

Безопасность аутентификации

Безопасность заказов

Технические детали

Архитектура сервиса

Операции с базой данных

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

Лучшие практики

Перед заказом циклов

После заказа циклов

Устранение неполадок

Частые проблемы

Справочник кодов ошибок

Ограничения частоты запросов

Заголовки ограничений

Превышение лимита (429)

Примечания