POST /apiv2/time/order

为指定地址购买特定数量的能量代理周期并为其激活 Host Mode。

端点 URL

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

身份验证

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

请求体

{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "cycles": 10
}

请求参数

Parameter	Type	Required	Description
api_key	string	Yes	API 密钥（或 X-API-KEY 请求头）。
address	string	Yes	TRON (TRC-20) 地址，^T[1-9A-HJ-NP-Za-km-z]{33}$。
cycles	integer	Yes	购买的周期数。必须 ≥ 1。

定价与计费

• 订购周期不会预先扣费。 每个周期在其能量被代理时计费：单次激活的首次代理费用为 4 TRX，后续每次代理费用为 2 或 4 TRX，具体取决于您上次转账实际消耗的能量（≤65,000 → 2 TRX，超出 → 4 TRX）。完整规则请参阅 Host Mode → 周期与定价，关于 8 TRX 的每日最低消费请参阅 每日最低消费（自 2026-08-29 起生效）。
• 响应中的 amount 是一个预估值（cycles × reference price），并非最终总额。
• 在接受订单前会检查您的余额；如果余额不足以支付订单，订单将被拒绝（错误 -2）。

提交订单会将地址设置为活跃状态，并针对所请求的周期数创建一个未完成订单。随后该地址开始逐个周期接收能量代理，每次代理在发生时扣费。

示例

cURL

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

Python

import requests

resp = requests.post(
    "https://netts.io/apiv2/time/order",
    json={
        "api_key": "YOUR_API_KEY_HERE",
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "cycles": 10,
    },
    timeout=30,
)
result = resp.json()

if result["code"] == 0:
    d = result["data"]
    print(f"Order {d['order_id']}: {d['cycles']} cycles for {d['amount']} TRX")
else:
    print("Error:", result["msg"])

Node.js

const axios = require('axios');

axios.post('https://netts.io/apiv2/time/order', {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    cycles: 10,
}).then(({ data: result }) => {
    if (result.code === 0) {
        const d = result.data;
        console.log(`Order ${d.order_id}: ${d.cycles} cycles for ${d.amount} TRX`);
    } else {
        console.error('Error:', result.msg);
    }
}).catch(err => console.error('Request failed:', err.response?.data || err.message));

响应

成功 (200 OK)

{
    "code": 0,
    "msg": "Cycles purchased and host mode activated successfully",
    "data": {
        "order_id": 5426,
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "cycles": 10,
        "amount": 23.5,
        "status": "active",
        "timestamp": "2026-07-13T05:30:15.123456"
    }
}

响应字段

Field	Type	Description
code	integer	0 = 成功，负数 = 错误
msg	string	人类可读的消息
data.order_id	integer	内部订单标识符
data.address	string	购买周期的目标地址
data.cycles	integer	购买的周期数
data.amount	number	订单预估总额，单位为 TRX（仅供参考 — 计费按次代理进行）
data.status	string	订单成功后为 "active"
data.timestamp	string	订单的 ISO 时间戳

错误响应

code	msg	Cause
-1	Invalid API key or IP not in whitelist	身份验证失败
-1	Invalid TRC-20 address format	地址格式错误
-1	Cycle count must be 1 or more	cycles < 1
-1	Database error processing order	临时服务端错误 — 请重试
-2	Insufficient balance. Required: X TRX, Available: Y TRX	余额低于订单总额
-6	Cannot buy cycles: There is an open order with … cycles for this address	已存在未完成订单（包括无限周期）

{
    "code": -2,
    "msg": "Insufficient balance. Required: 23.5 TRX, Available: 10.0 TRX"
}

目标地址不允许 (403)

在接受订单前会对地址进行检查。如果不允许向其代理资源，请求将被拒绝并返回 HTTP 403，且不会写入任何内容 — 不会创建订单，也不会添加或开启该地址。响应体使用 detail 格式：

code	msg	Meaning
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.	该地址已被冻结，无法接收资源代理

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

相关端点

• POST /apiv2/time/add — 先添加地址
• POST /apiv2/time/infinitystart — 无限周期而非固定数量
• POST /apiv2/time/status — 查询剩余周期
• POST /apiv2/time/stop — 停止并关闭订单

注意事项

• 如果该地址尚未处于 Host Mode，订购时也会将其注册并激活。
• 每个地址同一时间仅允许存在一个未完成订单。
• 购买的周期按每次代理消耗一个；耗尽后地址将自动停止。