POST /apiv2/address/rotate

Solicita a rotação de um endereço de depósito. O endereço de depósito atual será substituído por um novo. A solicitação é colocada em uma fila de processamento e concluída automaticamente dentro de 5 minutos.

URL do Endpoint

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

Cabeçalhos da Requisição

Cabeçalho	Obrigatório	Descrição
Content-Type	Sim	application/json
X-API-KEY	Sim	Sua chave de API do painel Netts
X-Real-IP	Sim	Endereço IP da sua whitelist

Corpo da Requisição

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

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
user_id	integer	Não	Usuário autenticado	ID do usuário de destino. Omita para rotacionar seu próprio endereço. Usuários pai podem especificar o ID de seu SUB-usuário
address_type	string	Não	"web"	Tipo de endereço a ser rotacionado: web ou tg

Autenticação e Autorização

Este endpoint requer tanto autenticação quanto autorização:

1. Autenticação: Chave de API válida + IP da whitelist (igual a outros endpoints)
2. Autorização:
   • Rotacionar seu próprio endereço — sempre permitido
   • Rotacionar o endereço do seu SUB-usuário — permitido para usuários pai
   • Rotacionar o endereço de outro usuário — rejeitado com 403 Forbidden

Exemplos de Requisição

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";
?>

Resposta

Resposta de Sucesso (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"
}

Campos da Resposta

Campo	Tipo	Descrição
rotation_id	integer	ID único da solicitação de rotação (use para verificações de status)
user_id	integer	Usuário cujo endereço está sendo rotacionado
address_type	string	Tipo de endereço sendo rotacionado (web ou tg)
old_address	string	Endereço de depósito TRON atual antes da rotação
status	string	Status da solicitação: pending
message	string	Mensagem de status legível para humanos
estimated_completion	string	Tempo estimado de conclusão no formato ISO 8601

Verificar Status da Rotação

GET /apiv2/address/rotate/status/

Verifica o status de uma solicitação de rotação enviada anteriormente.

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

Resposta:

{
    "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"
}

Valores de Status

Status	Descrição
pending	Solicitação enviada, aguardando para ser processada
processing	Sendo processada atualmente
completed	Novo endereço atribuído com sucesso
failed	Ocorreu um erro durante a rotação

Verificar Rotação Pendente

GET /apiv2/address/rotate/pending

Verifica se um usuário possui uma solicitação de rotação pendente (útil para desativar o botão de rotação).

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"

Resposta:

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

Observações Importantes

Alteração de Endereço

Após a conclusão da rotação, seu endereço de depósito atual não aceitará mais depósitos. Certifique-se de:

1. Retirar qualquer saldo restante do endereço atual antes de solicitar a rotação
2. Atualizar quaisquer sistemas externos que façam referência ao seu endereço de depósito antigo
3. Usar o novo endereço para todos os depósitos futuros

Tempo de Processamento

As solicitações de rotação são processadas automaticamente. Um novo endereço normalmente é atribuído dentro de 5 minutos após o envio.

• Apenas uma rotação pendente por usuário por tipo de endereço é permitida dentro de uma janela de 7 dias
• Se você já tiver uma rotação pendente, a solicitação será rejeitada com 409 Conflict
• Ambos os endereços web e tg podem ser rotacionados independentemente
• Usuários pai podem rotacionar os endereços de seus SUB-usuários especificando o parâmetro user_id

Respostas de Erro

Conflito (409)

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

Requisição Inválida (400)

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

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

Não Encontrado (404)

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

Proibido (403)

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

Erro de Autenticação (401)

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

Referência de Códigos de Erro

Status HTTP	Descrição
200	Solicitação de rotação enviada com sucesso
400	Requisição inválida (sem endereço, tipo inválido)
401	Cabeçalho de chave de API ausente
403	Não autorizado / Chave de API ou IP inválido
404	Usuário não encontrado / Rotação não encontrada
409	Rotação pendente já existente
500	Erro interno do servidor

Endpoints Relacionados

• POST /apiv2/subusergen — Criar um novo SUB-usuário
• DELETE /apiv2/subuserdel — Excluir um SUB-usuário
• GET /apiv2/userinfo — Obter informações do usuário