Energy Reclaim — дострокове повернення орендованої енергії

Повертайте делеговану Energy до пулу до закінчення терміну оренди. Корисно, коли транзакція, для якої ви орендували ресурси, вже надіслана: Energy перестає простоювати на адресі, і пул може обслужити когось іншого.

Повернення є добровільним. Термін оренди спливає самостійно — ви не зобов'язані викликати цей ендпоінт.

Базовий URL ендпоінта

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

Bandwidth має власний ендпоінт, див. Bandwidth.

Заголовки запиту

Header	Required	Description
X-API-KEY	Так	API-ключ, за допомогою якого було створено замовлення
X-Real-IP	Так	IP-адреса з вашого білого списку

Ваш user_id визначається на основі API-ключа — передавати його не потрібно.

Ключ має бути саме тим, що використовувався для замовлення

Замовлення можна повернути лише за допомогою того ключа, який його створив. Інший ключ того ж акаунту не спрацює.

---

Повернення — POST /apiv2/energy/reclaim/{orderId}

orderId — це номер замовлення, отриманий під час замовлення Energy, наприклад 1H… для 1-годинної оренди або 5M… для 5-хвилинної оренди. Тіло запиту відсутнє.

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 — це ончейн-транзакція, яка повернула Energy. Типовий час від запиту до відповіді становить кілька секунд.

Відповідь — вже повернуто (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" } }

Повертається як у разі, коли замовлення не існує, так і коли воно належить іншому акаунту.

---

Одне замовлення, а не одна адреса

Повернення працює позамовно, а не по адресах. Це зроблено навмисно: замовлення точно визначає, що саме повертається — одна й та сама адреса може містити Energy з кількох замовлень, включно із замовленнями інших акаунтів.

Два наслідки, які варто враховувати:

• Пакетне замовлення для багатьох адрес створює один номер замовлення на кожну адресу. Ви можете повернути будь-яке з них окремо; решта продовжуватиме діяти.
• Велика сума для однієї адреси може бути розбита на кілька замовлень. Щоб повністю звільнити цю адресу, поверніть кожне з них.

Повернення замовлень, створених через Orchestrator

Працює так само. Запитайте в Orchestrator статус вашого запиту, візьміть номер замовлення з поля energy.orderIds потрібної адреси та викличте повернення з ним:

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

Фінанси

Повернення не компенсує кошти. Оренда та повернення є окремими операціями: ви заплатили за оренду під час оформлення замовлення, і дострокове повернення ресурсу не скасовує цю оплату.

Обмеження швидкості (Rate limit)

10 запитів на секунду з однієї IP.

Коди помилок

Code	HTTP	Meaning
10004	200	Повернено, або вже повернено — хеш додано
5003	503	Прийнято, хеш ще не підтверджено — повторіть спробу незабаром
5005	400	Немає чого повертати для цього замовлення
5006	400	Замовлення зовнішнього провайдера — повернення недоступне
−1	404	Замовлення не знайдено або воно належить іншому акаунту
−1	401	Відсутній або недійсний API-ключ, або IP-адресу не додано до білого списку