Recuperação de Energy — devolver a energy alugada antecipadamente

Devolva a energy delegada ao pool antes do término do período de aluguel. Útil quando a transação para a qual você alugou já foi enviada: a energy deixa de ficar ociosa no endereço, e o pool pode atender a outra pessoa.

A recuperação é voluntária. Os aluguéis expiram por conta própria — você nunca precisa chamar este endpoint.

URL base do endpoint

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

Bandwidth tem seu próprio endpoint, consulte Bandwidth.

Cabeçalhos da Requisição

Cabeçalho	Obrigatório	Descrição
X-API-KEY	Sim	A chave de API com a qual o pedido foi feito
X-Real-IP	Sim	Endereço IP da sua whitelist

Seu user_id é derivado da chave de API — você nunca o envia.

A chave deve ser a mesma usada para o pedido

Um pedido só pode ser recuperado com a chave que o criou. Uma chave diferente da mesma conta não funcionará.

---

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

orderId é o número do pedido retornado quando a energy foi solicitada — por exemplo, 1H… para aluguéis de 1 hora ou 5M… para aluguéis de 5 minutos. Sem corpo na requisição.

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

Resposta — recuperada (200, código 10004)

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

reclaimHash é a transação on-chain que devolveu a energy. O tempo típico da requisição até a resposta é de alguns segundos.

Resposta — já recuperada (200, código 10004)

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

Chamar o endpoint duas vezes é seguro: a segunda chamada retorna o mesmo hash e não altera nada. Isso também abrange aluguéis que já expiraram por conta própria.

Resposta — provedor externo (400, código 5006)

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

Pedidos atendidos por um provedor externo não podem ser recuperados: os recursos não são nossos para devolver. Qual provedor atendeu a um pedido é visível na resposta do pedido.

Resposta — nada a recuperar (400, código 5005)

O pedido nunca resultou em uma delegação, ou a delegação não está ativa. Nada é cobrado e nada muda.

Resposta — ainda não concluído (503, código 5003)

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

A recuperação foi aceita, mas a transação on-chain não apareceu dentro da janela de espera. O mais provável é que ela seja concluída por conta própria — repita a chamada em alguns segundos para obter o hash.

Resposta — pedido não encontrado (404)

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

Retornado tanto quando o pedido não existe quanto quando pertence a uma conta diferente.

---

Um pedido, não um endereço

A recuperação funciona por pedido, não por endereço. Isso é deliberado: um pedido identifica exatamente o que está sendo devolvido — o mesmo endereço pode conter energy de vários pedidos, incluindo pedidos de outras contas.

Duas consequências que valem a pena planejar:

• Um pedido em lote para muitos endereços gera um número de pedido por endereço. Você recupera qualquer um deles individualmente; o restante continua funcionando.
• Uma quantidade grande para um único endereço pode ser dividida em vários pedidos. Para liberar esse endereço completamente, recupere cada um deles.

Recuperando pedidos feitos através do Orchestrator

Funciona da mesma maneira. Consulte o Orchestrator sobre o status da sua requisição, pegue o número do pedido no campo energy.orderIds do endereço desejado e chame a recuperação com ele:

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

Financeiro

A recuperação não reembolsa nada. O aluguel e a devolução são operações separadas: você pagou pelo aluguel quando fez o pedido, e devolver o recurso antecipadamente não anula esse pagamento.

Limite de taxa

10 requisições por segundo por IP.

Códigos de erro

Código	HTTP	Significado
10004	200	Recuperado ou já recuperado — hash incluído
5003	503	Aceito, hash ainda não confirmado — tente novamente em breve
5005	400	Nada a recuperar para este pedido
5006	400	Pedido de provedor externo — recuperação indisponível
−1	404	Pedido não encontrado ou pertence a outra conta
−1	401	Chave de API ausente ou inválida, ou IP não incluído na whitelist