POST /apiv2/address/rotate

请求轮换充值地址。当前充值地址将被替换为新地址。该请求会被放入处理队列，并在 5 分钟内自动完成。

接口 URL

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

请求头

请求头	必填	说明
Content-Type	是	application/json
X-API-KEY	是	来自 Netts 控制面板的 API 密钥
X-Real-IP	是	来自白名单的 IP 地址

请求体

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

参数

参数	类型	必填	默认值	说明
user_id	整数	否	已认证用户	目标用户 ID。省略此项则轮换您自己的地址。主账号用户可指定其子用户的 ID
address_type	字符串	否	"web"	要轮换的地址类型：web 或 tg

认证与授权

该接口需要同时进行认证和授权：

1. 认证：有效的 API 密钥 + 白名单 IP（与其他接口一致）
2. 授权：
   • 轮换您自己的地址 —— 始终允许
   • 轮换您的子用户的地址 —— 仅主账号用户允许
   • 轮换其他用户的地址 —— 将被拒绝并返回 403 Forbidden

请求示例

cURL

# 轮换自己的地址
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"}'

# 轮换子用户的地址（仅限主账号用户）
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	整数	唯一的轮换请求 ID（用于查询状态）
user_id	整数	正在轮换地址的用户
address_type	字符串	正在轮换的地址类型（web 或 tg）
old_address	字符串	轮换前的当前 TRON 充值地址
status	字符串	请求状态：pending
message	字符串	易读的状态消息
estimated_completion	字符串	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 地址均可独立轮换
• 主账号用户可以通过指定 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 — 创建新子用户
• DELETE /apiv2/subuserdel — 删除子用户
• GET /apiv2/userinfo — 获取用户信息