Energy Reclaim — return rented energy early

Return delegated energy to the pool before the rental period ends. Useful when the transaction you rented for is already sent: the energy stops sitting idle on the address, and the pool can serve someone else.

Reclaim is voluntary. Rentals expire on their own — you never have to call this endpoint.

Endpoint base URL

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

Bandwidth has its own endpoint, see Bandwidth.

Request Headers

Header	Required	Description
X-API-KEY	Yes	The API key the order was placed with
X-Real-IP	Yes	IP address from your whitelist

Your user_id is derived from the API key — you never pass it.

The key must be the one used for the order

An order can only be reclaimed with the key that created it. A different key of the same account will not work.

---

Reclaim — POST /apiv2/energy/reclaim/{orderId}

orderId is the order number returned when the energy was ordered — for example 1H… for 1-hour rentals or 5M… for 5-minute rentals. No request body.

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

Response — reclaimed (200, code 10004)

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

reclaimHash is the on-chain transaction that returned the energy. Typical time from request to response is a few seconds.

Response — already reclaimed (200, code 10004)

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

Calling the endpoint twice is safe: the second call returns the same hash and changes nothing. This also covers rentals that already expired on their own.

Response — external provider (400, code 5006)

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

Orders served by an external provider cannot be reclaimed: the resources are not ours to return. Which provider served an order is visible in the order response.

Response — nothing to reclaim (400, code 5005)

The order never resulted in a delegation, or the delegation is not active. Nothing is charged and nothing changes.

Response — not completed yet (503, code 5003)

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

The reclaim was accepted but the on-chain transaction had not appeared within the wait window. It will most likely complete on its own — repeat the call in a few seconds to get the hash.

Response — order not found (404)

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

Returned both when the order does not exist and when it belongs to a different account.

---

One order, not one address

Reclaim works per order, not per address. This is deliberate: an order identifies exactly what is being returned — the same address may hold energy from several orders, including orders of other accounts.

Two consequences worth planning for:

• A batch order for many addresses produces one order number per address. You reclaim any of them individually; the rest keep working.
• A large amount for a single address may be split into several orders. To free that address completely, reclaim each of them.

Reclaiming orders placed through the Orchestrator

Works the same way. Ask the Orchestrator for the status of your request, take the order number from the energy.orderIds field of the address you want, and call reclaim with it:

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

Money

Reclaim does not refund anything. Renting and returning are separate operations: you paid for the rental when you placed the order, and returning the resource early does not undo that payment.

Rate limit

10 requests per second per IP.

Error codes

Code	HTTP	Meaning
10004	200	Reclaimed, or already reclaimed — hash included
5003	503	Accepted, hash not confirmed yet — retry shortly
5005	400	Nothing to reclaim for this order
5006	400	External provider order — reclaim unavailable
−1	404	Order not found, or belongs to another account
−1	401	Missing or invalid API key, or IP not whitelisted