POST /apiv2/time/add

将 TRON 地址添加到 Host Mode，并可选择注册用于接收代理和暂停通知的回调 URL。

端点 URL

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

身份验证

在请求体（api_key）或 X-API-KEY 请求头中提供您的 API 密钥。请求 IP 必须位于为您的 API 密钥配置的白名单中。

请求体

json

{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",
    "infinity": true
}

请求参数

Parameter	Type	Required	Description
api_key	string	是*	API 密钥。也可以在 `X-API-KEY` 请求头中发送。
address	string	是	TRON (TRC-20) 地址，必须匹配 `^T[1-9A-HJ-NP-Za-km-z]{33}$`（以 `T` 开头，34 个字符）。
callback_url	string	否	公网 HTTP/HTTPS URL，用于在向该地址代理能量以及该地址的 Host Mode 被关闭时接收通知。最多 2048 个字符。
infinity	boolean	否	`true` — 同时直接将该地址切换到无尽模式，从而省去对 `/apiv2/time/infinitystart` 的单独调用。默认为 `false`。

* 除非使用了 X-API-KEY 请求头，否则在请求体中为必填。

**callback_url 验证：**必须是 http/https，且仅限公网主机（localhost、私有 RFC1918 范围、链路本地 169.254.0.0/16、IPv6 私有/链路本地、保留和多播地址均会被拒绝），最长 2048 个字符。

行为

如果该地址是新地址，它将被添加到 Host Mode 中，状态为未激活（status = 0，cycle_set = 0）。之后可通过 /apiv2/time/order 或 /apiv2/time/infinitystart 进行激活。
如果该地址已存在于您的账户下，该调用将更新其回调 URL。
如果提供了 callback_url，系统会为该地址存储（或更新）该 URL。

infinity

传入 "infinity": true 后，地址将在一次调用中被添加并以无尽模式激活 — 其效果等同于先调用 /apiv2/time/add，然后再调用 /apiv2/time/infinitystart。计费方式与单独调用完全相同：此时不收取任何费用，并且随着能量的代理逐周期扣费。请参阅 Host Mode → 周期与计费。

**添加地址和将其开启是两个独立的步骤，且仅第一步是有保证的。**响应返回的是添加的结果。如果地址已添加但未能开启，该调用仍然会返回带有常规消息的 code: 0 — 该地址只是保持未激活状态，效果与未传递该参数完全相同。在以下情况下将跳过开启：

您的余额不足以按当前价格支付一个周期；
地址已经处于激活状态；
地址已经有一个未结订单。

无论是否携带该标志，响应内容都是相同的 — 没有额外的字段，没有额外的错误代码，并且它不会告诉您无尽模式是否实际已被开启。请通过 Time Status 进行确认：该地址会返回 status: "active" 和 mode: "infinity"，且订单 ID 会包含在该响应中。请勿将此端点返回的 code: 0 视为该模式正在运行的凭证。

示例

cURL

bash

curl -X POST https://netts.io/apiv2/time/add \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/time/add"
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",  # optional
    # "infinity": True,  # optional: also switch the address into infinity mode
}

resp = requests.post(url, json=data, timeout=30)
result = resp.json()

if result["code"] == 0:
    print("Added:", result["data"]["address"])
else:
    print("Error:", result["msg"])

Node.js

javascript

const axios = require('axios');

const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    // callback_url: 'https://your-server.com/webhook', // optional
    // infinity: true, // optional: also switch the address into infinity mode
};

axios.post('https://netts.io/apiv2/time/add', data)
    .then(({ data: result }) => {
        if (result.code === 0) console.log('Added:', result.data.address);
        else console.error('Error:', result.msg);
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

响应

成功（新地址）

json

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://your-server.com/webhook",
        "timestamp": "2026-07-13T05:30:15.123456"
    }
}

成功（已存在地址更新回调 URL）

json

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2026-07-13T05:35:20.789012"
    }
}

响应字段

Field	Type	Description
code	integer	`0` = 成功，负数 = 错误
msg	string	人类可读的消息
data.address	string	已添加/更新的地址
data.callback_url	string \| null	已注册的回调 URL（如果没有则为 `null`）
data.timestamp	string	操作的 ISO 时间戳

错误响应

所有错误均使用 code = -1 并在 msg 中描述问题：

msg	原因
`API key required in X-API-KEY header or request body`	未提供 API 密钥
`Invalid API key or IP not in whitelist`	身份验证失败
`Invalid TRC-20 address format`	地址与所需格式不匹配
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	回调 URL 未通过验证
`Address belongs to another user`	该地址已在另一个账户下注册
`Database error adding/updating address`	临时服务器端错误 — 请重试
`Internal server error`	未预期的错误 — 请重试或联系客服

json

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

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": [ … ]}`	请求体未通过验证：缺少必填字段或类型错误。请注意此响应中没有 `code` 字段

目标地址不允许 (403)

地址在添加前会经过检查。如果该地址不允许接收资源代理，请求将被拒绝并返回 HTTP 403，且不会写入任何内容 — 地址既不会被添加也不会被开启。响应体采用 detail 结构：

code	msg	含义
1006	`Address is blocked. Contact support.`	地址已被封禁
1007	`Energy rental to smart contracts is not supported.`	地址是智能合约（GasFree 钱包地址也是智能合约）
1010	`Resource delegation to this address is not available.`	无法向此地址代理资源
1011	`This address is frozen and cannot receive resource delegation.`	地址已被冻结，无法接收资源代理

json

{ "detail": { "code": 1007, "msg": "Energy rental to smart contracts is not supported." } }

回调 (Webhook)

如果您注册了 callback_url，每当能量被代理到该地址时（即在处理每个代理周期时触发一次），以及每当该地址的 Host Mode 被关闭时，系统都会调用它 — 请参阅托管暂停事件。

请求格式

系统发送带有查询参数的 HTTP GET 请求：

由 USDT 转账产生的周期 — 包含 energy_used：

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149936&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=142.3500&idle_cycle=0&energy_used=65k&charged=2.0000

无前置转账的周期 — 省略 energy_used：

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149937&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=138.3500&idle_cycle=0&charged=4.0000

Parameter	Description
address	接收能量代理的 TRON 地址
order_id	代理标识符（`T` + 内部代理 ID）— 每次代理唯一
hash	能量代理的链上交易哈希
balance_after	本次扣费后您账户的 TRX 余额（扣费时的快照；在回调到达时可能已发生变化）
idle_cycle	`1` — 该代理是在 24 小时无转账后发出的（空闲重新代理），`0` — 由您的转账或激活产生的常规周期
energy_used	产生该周期的转账所消耗能量的资费档位：`65k`（65,000 能量或以下 → 2 TRX）或 `131k`（超过 65,000 → 4 TRX）。可选 — 当没有可供测量的前置转账时，查询字符串中完全省略该键（不会发送空值）：激活时的首次代理、每次空闲重新代理以及尚无消耗历史的地址。所有这些都按 4 TRX 的费率计费
charged	为此周期扣除的 TRX 金额 — `2.0000` 或 `4.0000`，与 `energy_used` 中的资费相匹配。始终存在，包括在省略 `energy_used` 时。请参阅 Host Mode → 周期与计费

使用 order_id 和 hash 来区分不同的代理并与您自己的记录进行对账 — 同一地址的两次回调通过这些值进行区分。使用 charged 跟踪每个周期的支出而无需轮询 /apiv2/time/status，并使用 energy_used 查看上一次转账落入哪个资费档位。请将 energy_used 作为可选参数处理 — 缺少该键意味着“没有可供测量的转账”，而不是错误，并且切勿为其假定默认值。

托管暂停事件

当该地址的 Host Mode 由于任何原因关闭（变为未激活）时，将调用相同的 callback_url：

GET https://your-server.com/webhook?event=host_paused&address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&reason=idle&paused_at=2026-09-13T11:16:58Z&balance=418.0000

Parameter	Description
event	对于此通知，始终为 `host_paused`
address	Host Mode 被关闭的 TRON 地址
reason	模式被关闭的原因 — 见下表
paused_at	模式被关闭的时间，ISO-8601 UTC
balance	当时您的账户 TRX 余额，保留 4 位小数

reason	含义
`idle`	连续 2 天空闲 — 两个 24 小时周期结束且均无转账（请参阅 Host Mode → 空闲关闭）
`cycles_exhausted`	所有订购的周期已耗尽
`no_balance`	您的余额不足以支付一个周期或每日最低充值金额
`stopped`	该模式已通过 `/apiv2/time/stop` 停止，或因任何其他原因关闭

**如何区分这两种通知：**只有暂停通知包含 event 参数；只有代理通知包含 order_id 和 hash。代理通知格式保持不变。

暂停后，该地址仍保留在 Host Mode 中及其回调 URL；可通过 /apiv2/time/order 或 /apiv2/time/infinitystart 再次开启。其投递机制与代理通知相同。

示例处理器 (Python / Flask)

python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['GET'])
def energy_delegation_webhook():
    address = request.args.get('address')
    order_id = request.args.get('order_id')
    tx_hash = request.args.get('hash')
    charged = request.args.get('charged')          # TRX charged for this cycle
    energy_used = request.args.get('energy_used')  # '65k' | '131k' | None (key may be absent)

    if not address:
        return jsonify({"error": "Missing address parameter"}), 400

    if request.args.get('event') == 'host_paused':
        # Host Mode switched off: reason = idle | cycles_exhausted | no_balance | stopped
        print(f"Host Mode paused: address={address} reason={request.args.get('reason')} "
              f"paused_at={request.args.get('paused_at')} balance={request.args.get('balance')}")
        return jsonify({"status": "success"}), 200

    # Your business logic (idempotent by order_id / hash)
    print(f"Energy delegated: address={address} order_id={order_id} hash={tx_hash} "
          f"charged={charged} energy_used={energy_used}")
    return jsonify({"status": "success"}), 200

投递行为

**方法：**GET，超时时间约 10 秒。返回 HTTP 200 进行确认。
**重试：**如果请求失败，最多尝试 3 次；如果全部失败，回调将被丢弃（无论如何能量代理仍会发生）。
**无签名：**请求未经 Netts 签名。密钥（如果有）是您嵌入在自己的 callback_url 中的任何内容。
**对账：**由于回调可能会丢失，因此还应轮询 /apiv2/time/status 并确保您的处理器具有幂等性。

更新/移除回调

**更新：**使用相同的地址和新的 callback_url 再次调用 /apiv2/time/add。
**移除：**调用 /apiv2/time/delete 移除该地址（这也会移除其回调）；如果需要，可以在不带 callback_url 的情况下重新添加。

注意事项

新地址初始状态为未激活；通过订单、无尽模式启动或在此处传入 "infinity": true 来激活它们。
同一地址不能在两个不同的账户下注册。
在添加地址之前，应先在 TRON 网络上将其激活。
智能合约 — 包括 GasFree 钱包地址 — 无法添加（HTTP 403，code 1007）。

POST /apiv2/time/add ​

端点 URL ​

身份验证 ​

请求体 ​

请求参数 ​

行为 ​

infinity ​

示例 ​

cURL ​

Python ​

Node.js ​

响应 ​

成功（新地址） ​

成功（已存在地址更新回调 URL） ​

响应字段 ​

错误响应 ​

HTTP 状态码 ​

目标地址不允许 (403) ​

回调 (Webhook) ​

请求格式 ​

托管暂停事件 ​

示例处理器 (Python / Flask) ​

投递行为 ​

更新/移除回调 ​

相关端点 ​

注意事项 ​

POST /apiv2/time/add

端点 URL

身份验证

请求体

请求参数

行为

infinity

示例

cURL

Python

Node.js

响应

成功（新地址）

成功（已存在地址更新回调 URL）

响应字段

错误响应

HTTP 状态码

目标地址不允许 (403)

回调 (Webhook)

请求格式

托管暂停事件

示例处理器 (Python / Flask)

投递行为

更新/移除回调

相关端点

注意事项