Energy 回收 — 提前归还租用的能量

在租赁期结束前将委托的能量归还至资金池。当您租用能量所针对的交易已经发送完毕时非常有用：能量不再闲置在地址上，资金池可以为其他人提供服务。

回收是自愿的。租赁会自动到期 — 您无需必须调用此端点。

端点基础 URL

https://netts.io/apiv2/energy/reclaim

Bandwidth 拥有其专属端点，请参见 Bandwidth。

请求标头

标头	必填	描述
X-API-KEY	是	下单时使用的 API 密钥
X-Real-IP	是	来自您白名单的 IP 地址

您的 user_id 是从 API 密钥派生的 — 您无需传递它。

密钥必须是下单时使用的那一个

订单只能使用创建它的密钥进行回收。同一账户下的其他密钥将无法生效。

---

回收 — POST /apiv2/energy/reclaim/{orderId}

orderId 是订购能量时返回的订单号 — 例如针对 1 小时租赁的 1H… 或针对 5 分钟租赁的 5M…。无请求体。

curl -X POST "https://netts.io/apiv2/energy/reclaim/1Hb252feadcc" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip"

响应 — 已回收 (200, 状态码 10004)

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Energy reclaimed",
        "data": {
            "orderId": "1Hb252feadcc",
            "reclaimHash": "51fa77da06e8fbebf504fbf088d1d9611059398d…"
        }
    }
}

reclaimHash 是归还能量的链上交易哈希。从请求到响应的典型耗时为几秒钟。

响应 — 已经回收 (200, 状态码 10004)

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Energy already reclaimed",
        "data": {
            "orderId": "1Hb252feadcc",
            "reclaimHash": "51fa77da06e8fbebf504fbf088d1d9611059398d…"
        }
    }
}

重复调用该端点是安全的：第二次调用会返回相同的哈希且不做任何更改。这也适用于已自行过期的租赁。

响应 — 外部服务商 (400, 状态码 5006)

{
    "detail": {
        "code": 5006,
        "status": "failed",
        "msg": "Reclaim is available only for internal pool orders",
        "data": { "orderId": "1H47eac983af", "provider": "…" }
    }
}

由外部服务商提供服务的订单无法回收：这些资源不属于我们，因而无法归还。订单由哪个服务商提供可在订单响应中查看。

响应 — 无可回收内容 (400, 状态码 5005)

订单从未产生委托，或者委托未处于活动状态。不收取任何费用，也不做任何更改。

响应 — 尚未完成 (503, 状态码 5003)

{
    "detail": {
        "code": 5003,
        "status": "failed",
        "msg": "Reclaim not completed yet — try again shortly",
        "data": { "orderId": "1Hb252feadcc" }
    }
}

回收请求已被受理，但链上交易未在等待窗口期内出现。它很可能会自行完成 — 请在几秒钟后重试调用以获取哈希。

响应 — 未找到订单 (404)

{ "detail": { "code": -1, "msg": "Order not found" } }

在订单不存在以及订单属于其他账户时均会返回。

---

按订单回收，而非按地址

回收操作是按订单进行的，而不是按地址。这是刻意设计的：订单精确标识了正在归还的内容 — 同一个地址可能持有来自多个订单的能量，包括其他账户的订单。

值得提前规划的两个影响：

• 针对多个地址的批量订单会为每个地址生成一个订单号。您可以单独回收其中的任何一个；其余订单不受影响继续工作。
• 单个地址的大额数量可能会被拆分为多个订单。要完全释放该地址的资源，请回收其中的每一个订单。

回收通过 Orchestrator 创建的订单

运作方式相同。向 Orchestrator 查询您的请求状态，从所需地址的 energy.orderIds 字段中获取订单号，并使用它调用回收：

"energy": {
    "requested": 65570,
    "delegated": 65570,
    "status": "done",
    "orderIds": ["1Hb252feadcc"]
}

费用相关

回收不会进行任何退款。租用与归还是独立的操作：您在下单时已经支付了租赁费用，提前归还资源不会撤销该笔付款。

速率限制

每个 IP 每秒 10 次请求。

错误代码

代码	HTTP	含义
10004	200	已回收，或已经回收 — 包含哈希
5003	503	已受理，哈希尚未确认 — 请稍后重试
5005	400	该订单无可回收内容
5006	400	外部服务商订单 — 回收不可用
−1	404	未找到订单，或属于其他账户
−1	401	缺少或无效的 API 密钥，或 IP 未加入白名单