Energy Reclaim — devolver energía alquilada antes de tiempo

Devuelva la energía delegada al pool antes de que finalice el período de alquiler. Útil cuando la transacción para la que alquiló ya se ha enviado: la energía deja de estar inactiva en la dirección y el pool puede prestar servicio a otra persona.

Reclaim es voluntario. Los alquileres vencen por sí solos — nunca es obligatorio llamar a este endpoint.

URL base del endpoint

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

Bandwidth tiene su propio endpoint, consulte Bandwidth.

Encabezados de solicitud

Encabezado	Obligatorio	Descripción
X-API-KEY	Sí	La API key con la que se realizó la orden
X-Real-IP	Sí	Dirección IP de su lista blanca

Su user_id se deriva de la API key — nunca es necesario enviarlo.

La clave debe ser la misma utilizada para la orden

Una orden solo se puede reclamar con la clave que la creó. Una clave diferente de la misma cuenta no funcionará.

---

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

orderId es el número de orden devuelto cuando se solicitó la energía — por ejemplo 1H… para alquileres de 1 hora o 5M… para alquileres de 5 minutos. Sin cuerpo de solicitud.

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

Respuesta — reclamada (200, código 10004)

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

reclaimHash es la transacción on-chain que devolvió la energía. El tiempo típico desde la solicitud hasta la respuesta es de unos pocos segundos.

Respuesta — ya reclamada (200, código 10004)

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

Llamar al endpoint dos veces es seguro: la segunda llamada devuelve el mismo hash y no cambia nada. Esto también cubre los alquileres que ya vencieron por sí solos.

Respuesta — proveedor externo (400, código 5006)

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

Las órdenes atendidas por un proveedor externo no se pueden reclamar: los recursos no son nuestros para devolverlos. El proveedor que atendió una orden es visible en la respuesta de la orden.

Respuesta — nada que reclamar (400, código 5005)

La orden nunca resultó en una delegación, o la delegación no está activa. No se cobra nada y nada cambia.

Respuesta — aún no completada (503, código 5003)

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

El reclaim fue aceptado pero la transacción on-chain no había aparecido dentro del período de espera. Lo más probable es que se complete por sí sola — repita la llamada en unos segundos para obtener el hash.

Respuesta — orden no encontrada (404)

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

Se devuelve tanto cuando la orden no existe como cuando pertenece a una cuenta diferente.

---

Una orden, no una dirección

Reclaim funciona por orden, no por dirección. Esto es deliberado: una orden identifica exactamente lo que se está devolviendo — la misma dirección puede contener energía de varias órdenes, incluidas órdenes de otras cuentas.

Dos consecuencias que vale la pena planificar:

• Una orden por lotes para muchas direcciones genera un número de orden por dirección. Puede reclamar cualquiera de ellas individualmente; el resto sigue funcionando.
• Una cantidad grande para una sola dirección puede dividirse en varias órdenes. Para liberar esa dirección por completo, reclame cada una de ellas.

Reclamar órdenes realizadas a través del Orchestrator

Funciona de la misma manera. Solicite al Orchestrator el estado de su solicitud, tome el número de orden del campo energy.orderIds de la dirección deseada y llame a reclaim con él:

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

Dinero

Reclaim no reembolsa nada. Alquilar y devolver son operaciones independientes: usted pagó por el alquiler al realizar la orden, y devolver el recurso antes de tiempo no revierte ese pago.

Límite de tasa

10 solicitudes por segundo por IP.

Códigos de error

Código	HTTP	Significado
10004	200	Reclamada, o ya reclamada — hash incluido
5003	503	Aceptada, hash aún no confirmado — reintente en breve
5005	400	Nada que reclamar para esta orden
5006	400	Orden de proveedor externo — reclaim no disponible
−1	404	Orden no encontrada, o pertenece a otra cuenta
−1	401	Clave API ausente o inválida, o IP no incluida en la lista blanca