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	整数	是	租赁的能量数量（最小值：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": "3636f97dde244fca17cdc0b2cf7fd157...",
            "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": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc..."
        }
    }
}

响应字段

字段	类型	描述
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": "3636f97dde244fca17cdc0b2cf7fd157...",
            "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 分钟费率）	标准小时费率
可用性	高峰期可能受限	高（多提供商回退机制）
适用场景	频繁的小额交易	大额或保证交付的交易

注意事项

订单成功后能量即时交付（通常在 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 小时订单 ​

注意事项 ​

POST /apiv2/order5m

端点 URL

请求标头

请求体

请求参数

提供商信息

示例

cURL

Python

响应

成功响应 (200 OK)

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

响应字段

错误响应

无效能量数量 (400)

身份验证错误 (401)

余额不足 (403)

服务不可用 (503)

内部服务器错误 (500)

错误代码参考

速率限制

速率限制请求头

超出速率限制 (429)

幂等性

幂等性的工作原理

提供您自己的密钥

发送两个相同订单

重复请求的 HTTP 状态码

重复请求 - 已处理 (208)

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

最佳实践

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

注意事项