POST /apiv2/address/rotate

Запит на ротацію адреси для депозиту. Поточну адресу для депозиту буде замінено на нову. Запит поміщається в чергу обробки та виконується автоматично протягом 5 хвилин.

URL ендпоінту

POST https://netts.io/apiv2/address/rotate

Заголовки запиту

Заголовок	Обов'язковий	Опис
Content-Type	Так	application/json
X-API-KEY	Так	Ваш API-ключ із панелі керування Netts
X-Real-IP	Так	IP-адреса з вашого білого списку

Тіло запиту

{
    "user_id": 1234,
    "address_type": "web"
}

Параметри

Параметр	Тип	Обов'язковий	За замовчуванням	Опис
user_id	integer	Ні	Автентифікований користувач	ID цільового користувача. Пропустіть, щоб виконати ротацію власної адреси. Батьківські користувачі можуть вказати ID свого SUB-користувача
address_type	string	Ні	"web"	Тип адреси для ротації: web або tg

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

Цей ендпоінт вимагає як автентифікації, так і авторизації:

1. Автентифікація: Дійсний API-ключ + IP з білого списку (так само, як і для інших ендпоінтів)
2. Авторизація:
   • Ротація власної адреси — дозволено завжди
   • Ротація адреси вашого SUB-користувача — дозволено для батьківських користувачів
   • Ротація адреси іншого користувача — відхиляється з помилкою 403 Forbidden

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

cURL

# Rotate own address
curl -X POST https://netts.io/apiv2/address/rotate \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{"address_type": "web"}'

# Rotate SUB-user's address (parent user only)
curl -X POST https://netts.io/apiv2/address/rotate \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{"user_id": 1234, "address_type": "web"}'

Python

import requests

url = "https://netts.io/apiv2/address/rotate"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

# Rotate own address
response = requests.post(url, headers=headers, json={"address_type": "web"})
data = response.json()

if response.status_code == 200:
    print(f"Rotation ID: {data['rotation_id']}")
    print(f"Old Address: {data['old_address']}")
    print(f"Status: {data['status']}")
    print(f"Estimated Completion: {data['estimated_completion']}")
else:
    print(f"Error: {data.get('detail', 'Unknown error')}")

Node.js

const axios = require('axios');

async function rotateAddress(apiKey, whitelistedIp, addressType = 'web', userId = null) {
    const url = 'https://netts.io/apiv2/address/rotate';
    const body = { address_type: addressType };
    if (userId) body.user_id = userId;

    const response = await axios.post(url, body, {
        headers: {
            'Content-Type': 'application/json',
            'X-API-KEY': apiKey,
            'X-Real-IP': whitelistedIp
        },
        timeout: 30000
    });

    const data = response.data;
    console.log(`Rotation ID: ${data.rotation_id}`);
    console.log(`Status: ${data.status}`);
    console.log(`Old Address: ${data.old_address}`);
    return data;
}

// Rotate own address
rotateAddress('your_api_key', 'your_whitelisted_ip')
    .then(result => console.log('Submitted:', result.message))
    .catch(err => console.error('Error:', err.response?.data || err.message));

PHP

<?php
$url = 'https://netts.io/apiv2/address/rotate';

$data = json_encode([
    'address_type' => 'web'
]);

$options = [
    'http' => [
        'header' => implode("\r\n", [
            "Content-Type: application/json",
            "X-API-KEY: your_api_key",
            "X-Real-IP: your_whitelisted_ip"
        ]),
        'method' => 'POST',
        'content' => $data,
        'timeout' => 30
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response, true);

echo "Rotation ID: {$result['rotation_id']}\n";
echo "Old Address: {$result['old_address']}\n";
echo "Status: {$result['status']}\n";
echo "Message: {$result['message']}\n";
?>

Відповідь

Успішна відповідь (200 OK)

{
    "rotation_id": 42,
    "user_id": 1234,
    "address_type": "web",
    "old_address": "TCurrentAddress1234567890123456789",
    "status": "pending",
    "message": "Address rotation request submitted. New address will be assigned within 5 minutes.",
    "estimated_completion": "2026-03-14T12:35:00Z"
}

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

Поле	Тип	Опис
rotation_id	integer	Унікальний ID запиту на ротацію (використовується для перевірки статусу)
user_id	integer	Користувач, для адреси якого виконується ротація
address_type	string	Тип адреси, для якої виконується ротація (web або tg)
old_address	string	Поточна TRON-адреса для депозиту перед ротацією
status	string	Статус запиту: pending
message	string	Зрозуміле для людини повідомлення про статус
estimated_completion	string	Орієнтовний час завершення у форматі ISO 8601

Перевірка статусу ротації

GET /apiv2/address/rotate/status/

Перевірити статус раніше надісланого запиту на ротацію.

curl https://netts.io/apiv2/address/rotate/status/42 \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip"

Відповідь:

{
    "rotation_id": 42,
    "user_id": 1234,
    "address_type": "web",
    "status": "completed",
    "old_address": "TOldAddress1234567890123456789012",
    "new_address": "TNewAddress1234567890123456789012",
    "created_at": "2026-03-14T12:30:00Z",
    "completed_at": "2026-03-14T12:34:15Z"
}

Значення статусу

Статус	Опис
pending	Запит надіслано, очікує на обробку
processing	Наразі обробляється
completed	Нову адресу успішно призначено
failed	Під час ротації сталася помилка

Перевірка активної ротації

GET /apiv2/address/rotate/pending

Перевірити, чи має користувач активний запит на ротацію (корисно для вимкнення кнопки ротації).

curl "https://netts.io/apiv2/address/rotate/pending?address_type=web" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip"

Відповідь:

{
    "user_id": 1234,
    "address_type": "web",
    "has_pending": true,
    "pending_rotation": {
        "rotation_id": 42,
        "status": "pending",
        "created_at": "2026-03-14T12:30:00Z"
    }
}

Важливі примітки

Зміна адреси

Після завершення ротації ваша поточна адреса для депозиту більше не прийматиме депозити. Обов'язково:

1. Виведіть увесь залишок балансу з поточної адреси перед тим, як подавати запит на ротацію
2. Оновіть усі зовнішні системи, які посилаються на вашу стару адресу для депозиту
3. Використовуйте нову адресу для всіх майбутніх депозитів

Час обробки

Запити на ротацію обробляються автоматично. Нова адреса зазвичай призначається протягом 5 хвилин після надсилання.

• Дозволено лише одну активну ротацію на користувача для кожного типу адреси протягом 7-денного періоду
• Якщо у вас уже є активний запит на ротацію, запит буде відхилено з помилкою 409 Conflict
• Як web, так і tg адреси можуть бути змінені незалежно одна від одної
• Батьківські користувачі можуть виконувати ротацію адрес своїх SUB-користувачів, вказавши параметр user_id

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

Конфлікт (409)

{
    "detail": "User 1234 already has a pending web address rotation request"
}

Некоректний запит (400)

{
    "detail": "User 1234 has no web deposit address"
}

{
    "detail": "address_type must be 'web' or 'tg'"
}

Не знайдено (404)

{
    "detail": "User 9999 not found"
}

Заборонено (403)

{
    "detail": "Not authorized to rotate this user's address"
}

Помилка автентифікації (401)

{
    "detail": "X-API-KEY header required"
}

Довідник кодів помилок

HTTP-статус	Опис
200	Запит на ротацію успішно надіслано
400	Некоректний запит (немає адреси, недійсний тип)
401	Відсутній заголовок API-ключа
403	Немає авторизації / Недійсний API-ключ або IP
404	Користувача не знайдено / Ротацію не знайдено
409	Активна ротація вже існує
500	Внутрішня помилка сервера

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

• POST /apiv2/subusergen — Створити нового SUB-користувача
• DELETE /apiv2/subuserdel — Видалити SUB-користувача
• GET /apiv2/userinfo — Отримати інформацію про користувача