POST /apiv2/order5m

通过 Netts 内部能量池创建 5 分钟能量租赁订单。

端点 URL

POST https://netts.io/apiv2/order5m

请求标头

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

请求正文

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

参数

参数	类型	必填	说明
amount	整数	是	租赁的 Energy 数量（最小值：61,000，最大值：650,000）
receiveAddress	字符串	是	接收能量的 TRON 地址（TRC-20 格式）

能量限制

5 分钟端点每笔订单接受 61,000 到 650,000 单位之间的能量数量。超出此范围的请求将被拒绝并返回 HTTP 400。

供应商信息

5 分钟能量订单完全通过 Netts 内部能量池完成。与 1 小时端点不同，此处不使用外部供应商。

可用性与重试策略

由于质押代理仅来自内部池，在高需求期间可能会出现暂时不可用的情况。如果您收到 503 错误，请在短暂延迟后重试请求，或者回退到可以使用多个外部供应商的 1 小时端点。

请求示例

cURL

bash

curl -X POST https://netts.io/apiv2/order5m \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

python

import requests

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

payload = {
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

响应

成功响应 (200 OK)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

包含地址激活的成功响应 (200 OK)

当接收地址尚未在 TRON 网络上激活时，Netts 会自动激活它。激活费用将计入总额：

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a"
        }
    }
}

响应字段

字段	类型	说明
detail.code	整数	成功订单始终为 `10000`
detail.msg	字符串	包含扣除金额的成功消息
detail.data.orderId	字符串	统一订单 ID（格式：`5M{id}`）
detail.data.paidTRX	数字	TRX 总费用（如适用，包含激活费）
detail.data.hash	字符串	质押代理交易哈希
detail.data.delegateAddress	字符串	代理能量的池地址
detail.data.energy	整数	能量数量 + 缓冲（通常为 +50）
detail.data.activationHash	字符串	仅在执行了地址激活时存在

错误响应

无效的能量数量 (400)

json

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

身份验证错误 (401)

json

{
    "detail": "Invalid API key or IP not in whitelist"
}

余额不足 (403)

json

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

服务不可用 (503)

json

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

处理 503 错误

503 响应表示内部池暂时达到容量上限。推荐策略：

等待 2-3 秒并重试 5 分钟订单
如果仍然不可用，回退到使用多个供应商的 1 小时端点

内部服务器错误 (500)

json

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

错误代码参考

代码	说明	HTTP 状态
`10000`	成功	200
`10000`	成功（缓存响应）	208
`-`	重复请求仍在处理中	409
`1003`	能量数量超出范围	400
`1004`	余额不足	403
`1005`	未配置用户付款人地址	400
`5000`	内部服务器错误	500
`5003`	能量服务不可用	503

速率限制

以下速率限制适用于此端点（按 IP 地址）：

周期	限制	说明
1 秒	50 次请求	每秒最多 50 次请求

速率限制标头

http

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

超出速率限制 (429)

json

{
    "message": "API rate limit exceeded"
}

幂等性

API 支持幂等性以防止重复处理订单。当您发送多个相同的请求时，系统可确保订单仅被处理一次。

幂等性的工作原理

请求的唯一性由以下组合确定：

请求时间戳（2 秒窗口）
能量数量
接收地址
API 密钥

每个请求都有一个 2 秒的唯一性窗口。在该窗口内具有相同参数的请求将被视为重复请求。

提供您自己的密钥

您可以通过发送 X-Idempotency-Key 标头自行管理幂等性。当该标头存在时，仅凭该值即可判定请求是否为重复请求，且不使用上述自动组合。当它不存在时，一切保持不变——服务器将为您派生密钥。

规则与 /apiv2/order1h 相同：


标头	`X-Idempotency-Key`
格式	正好 64 个小写十六进制字符——SHA-256 摘要
生命周期	自携带该密钥的第一个请求起 24 小时
范围	您的账户。不同账户发送的相同值绝不会返回您的结果

任何其他形式的密钥——带有短横线的 UUID、base64、大写十六进制——都会在下单和产生任何费用之前被拒绝并返回 400：

json

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

从您的 API 密钥派生此密钥，使其对您的账户唯一且在重试时可复现——具体示例请参见 1 小时页面。在您进行哈希的消息中包含租赁周期：将同一地址租赁 5 分钟和租赁 1 小时属于不同的订单，两者重复使用同一个密钥将导致第二个请求返回第一个订单的响应。

下发两个相同的订单

这与每小时端点的陷阱相同，只是时间窗口更宽。两个相同的订单——向相同的地址请求相同的数量——与重试无法区分，只有到达时刻能将它们区分开来。

在没有您自己的密钥的情况下：

两个请求之间的间隔	发生的情况
在同一个 2 秒窗口内	第二个请求被视为重复请求。它不会被执行：您会收到 `208` 以及第一个订单的响应。不会对其扣费
间隔超过两秒	视为两个不同的密钥——两个订单均已下发并扣费

因此，请在两个相同的订单之间保留两秒以上的间隔，并查看状态代码：208 意味着您刚刚发送的订单未被下发。

暂停是一种变通方案，而不是根本解决办法——它同样会把您从未打算重复的请求隔开，例如超时后的重试或队列重新投递的消息，而这些请求中的每一个都会变成单独的订单并单独收费。发送您自己的密钥才能真正解决此问题：新订单使用新的 nonce，重试使用首次尝试的 nonce。完整的原理解释请参见 1 小时页面。

重复请求的 HTTP 状态代码

状态代码	名称	说明
200	OK	订单处理成功（首次请求）
208	Already Reported	订单已被处理，返回缓存的响应
409	Conflict	请求当前正在处理中，请勿重试

重复请求 - 已处理 (208)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

重复请求 - 仍在处理中 (409)

json

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "retry_after_seconds": 3
}

最佳实践

请勿发送带有相同参数的并行请求 - 等待每次响应
通过等待来处理 409 响应，而不是立即重试
检查 idempotency.cached 字段以识别缓存响应

对比：5 分钟订单与 1 小时订单

功能	5 分钟订单	1 小时订单
端点	`/apiv2/order5m`	`/apiv2/order1h`
时长	5 分钟	1 小时
能量范围	61,000 - 650,000	61,000 - 3,000,000
供应商	仅限 Netts 内部池	内部池 + 外部供应商
价格	较低（5 分钟费率）	标准小时费率
可用性	高峰期可能受限	高（多供应商回退）
最适用于	频繁的小额交易	大额或有保障的交付

后付费账户

采用后付费计费的账户使用与其他所有人相同的端点、URL、标头和请求正文。区别在于订单的支付方式：

不会从您的押金中扣除任何费用。 每笔成功的订单都会以合同中约定的结算货币计入您的账户应付余额。您根据协议按发票付款。
您的账户拥有信用额度。只要应付金额在额度范围内，即使押金为零也会接受订单。
仅对已交付的服务进行计费。被拒绝或未执行的订单不产生任何费用。
如果必须激活接收地址，激活将作为同一订单的一部分，并作为单独费用计费。

后付费计费由 Netts 根据请求为账户启用。每个响应都会告知您订单的支付方式：paymentMode 为 postpaid 或 prepaid。

附加请求字段

参数	类型	必填	说明
test	布尔值	否	`true` — 仅计算价格。不下单、不交付、不计费
freezePrice	布尔值	否	`true` — 锁定您合同项下的价格 60 秒。不下单、不计费
quoteId	字符串	否	按照由 `freezePrice` 签发的报价单价格下单
priceCurrency	字符串	否	`TRX`（默认）或您合同的货币，如 `settlement.asset` 中所示。对于后付费账户，始终包含以您合同货币计价的金额

quoteId 不能与 test 或 freezePrice 同时使用。请求正文中的任何其他字段都将被拒绝。

价格查询 (`test: true`)

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "test": true
}

json

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 65000,
            "unitPriceSun": "19",
            "discount": null,
            "energyTRX": "1.235000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "2.335000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.409088", "activation": "0.364370", "total": "0.773458"}},
            "fxAt": "2026-10-19T07:16:12.548894+00:00"
        }
    }
}

字段	说明
unitPriceSun	每单位能量的价格（以 SUN 为单位），包含您的个人折扣（如果有）
discount	您的个人折扣（`type`、`value`）或 `null`
energyTRX / activationTRX / wouldCostTRX	能量、激活（如果地址需要）和总计金额，以 TRX 计价
activationCheck	`inactive` — 地址将被激活并计费；`active` — 无需激活；`unknown` — 目前无法检查
`alt.<currency>`	以您合同货币计价的相同金额
fxAt	用于换算合同货币金额的汇率时间

固定价格报价 (`freezePrice: true`)

在下单前使用报价锁定您合同项下的价格。

发送带有 "freezePrice": true 的订单。响应代码为 10011（Quote issued），字段与价格查询相同，外加 quoteId 和 expiresAt。
在 60 秒内发送带有 "quoteId": "<quoteId>" 以及相同的 amount 和 receiveAddress 的订单。
订单按报价的价格计费——即报价时刻您合同项下的价格——即使在此期间价格发生变化。

报价可使用一次，且仅适用于同一产品：5 分钟报价不能用于支付 1 小时订单。过期或已使用的报价将被拒绝，且不会下发任何订单。

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "quoteId": "q_4f540f16a2c94b7f8e3d1a6b5c0e9d72"
}

成功订单

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.24 TRX service cost, postpaid",
        "data": {
            "orderId": "5M5f557d2fba",
            "paidTRX": 1.235,
            "hash": "c1fafd8ef7fb6b7fb8a729120756b26e611f401275cb4f7a04fe2bafd75b13da",
            "delegateAddress": "TR3qZsdmkFcvP729Md3PwXzktFQkMoUzjg",
            "energy": 65000,
            "paymentMode": "postpaid",
            "energyTRX": "1.235000",
            "activationTRX": "0.000000",
            "totalTRX": "1.235000"
        }
    }
}

字段	说明
paidTRX	服务费用（以 TRX 计）。对于后付费账户，不会从押金中扣除
paymentMode	`postpaid`
energyTRX / activationTRX / totalTRX	精确金额，保留 6 位小数
quoteId, alt	当订单通过报价下发时存在：报价 ID 和报价金额

所有其他字段与预付费订单相同。

达到信用额度 (402)

json

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

订单未执行且不计费。一旦您的付款登记入账或额度提升，将重新开始接受新订单。

后付费错误代码

代码	HTTP	说明
`10010`	200	价格查询结果 (`test`)
`10011`	200	报价已签发 (`freezePrice`)
`1004`	402	达到后付费信用额度
`4100`	400	无效请求
`4101`	400	不支持的 `priceCurrency`
`4102`	400	`quoteId` 与 `test` 或 `freezePrice` 混用
`4103`	409	报价已被使用
`4104`	409	报价已过期
`4105`	409	幂等性密钥已被其他请求使用
`4106`	404	未找到报价
`4107`	409	订单参数与报价不符
`4108`	400	无效的 `quoteId` 格式
`4109`	422	不适用于子账户
`5032`	503	价格暂时不可用
`5033`	503	汇率暂时不可用
`5034`	503	计费服务暂时不可用 — 订单未被接受
`5036`	503	信用检查暂时不可用 — 请稍后重试

对于上述所有 4xx 和 503 响应，均不下单且不计费。

注意事项

订单成功后立即交付能量（通常在 0.5-2 秒内）
API 响应超时：最长 10 秒（包含内部重试尝试）
地址激活：如果接收地址未激活，Netts 会按成本价将其激活。每个地址仅收取一次激活费用
时长：固定 5 分钟（300 秒）
最小能量数量：61,000 单位
最大能量数量：每笔订单 650,000 单位
能量缓冲：自动额外增加 +50 单位（免费）
订单 ID 格式：5M{id} 用于统一跟踪
定价：通过定价 API根据一天中的时间动态调整
速率限制：每个 IP 地址每秒 50 次请求
仅限内部池：如果池已满负荷，请在短暂延迟后重试，或使用 1 小时端点作为回退方案

POST /apiv2/order5m ​

端点 URL ​

请求标头 ​

请求正文 ​

参数 ​

供应商信息 ​

请求示例 ​

cURL ​

Python ​

响应 ​

成功响应 (200 OK) ​

包含地址激活的成功响应 (200 OK) ​

响应字段 ​

错误响应 ​

无效的能量数量 (400) ​

身份验证错误 (401) ​

余额不足 (403) ​

服务不可用 (503) ​

内部服务器错误 (500) ​

错误代码参考 ​

速率限制 ​

速率限制标头 ​

超出速率限制 (429) ​

幂等性 ​

幂等性的工作原理 ​

提供您自己的密钥 ​

下发两个相同的订单 ​

重复请求的 HTTP 状态代码 ​

重复请求 - 已处理 (208) ​

重复请求 - 仍在处理中 (409) ​

最佳实践 ​

对比：5 分钟订单与 1 小时订单 ​

后付费账户 ​

附加请求字段 ​

价格查询 (test: true) ​

固定价格报价 (freezePrice: true) ​

成功订单 ​

达到信用额度 (402) ​

后付费错误代码 ​

注意事项 ​

POST /apiv2/order5m

端点 URL

请求标头

请求正文

参数

供应商信息

请求示例

cURL

Python

响应

成功响应 (200 OK)

包含地址激活的成功响应 (200 OK)

响应字段

错误响应

无效的能量数量 (400)

身份验证错误 (401)

余额不足 (403)

服务不可用 (503)

内部服务器错误 (500)

错误代码参考

速率限制

速率限制标头

超出速率限制 (429)

幂等性

幂等性的工作原理

提供您自己的密钥

下发两个相同的订单

重复请求的 HTTP 状态代码

重复请求 - 已处理 (208)

重复请求 - 仍在处理中 (409)

最佳实践

对比：5 分钟订单与 1 小时订单

后付费账户

附加请求字段

价格查询 (`test: true`)

固定价格报价 (`freezePrice: true`)

成功订单

达到信用额度 (402)

后付费错误代码

注意事项