Energy Reclaim — досрочный возврат арендованной энергии

Возврат делегированной энергии в пул до окончания срока аренды. Полезно, когда транзакция, для которой вы арендовали ресурсы, уже отправлена: энергия не простаивает на адресе, а пул может обслужить кого-то другого.

Возврат является добровольным. Срок аренды истекает сам по себе — вам необязательно вызывать этот эндпоинт.

Базовый 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 — это номер заказа, возвращенный при заказе энергии, например 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 — это ончейн-транзакция, вернувшая энергию. Стандартное время от запроса до ответа составляет несколько секунд.

Ответ — уже отозвано (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"]
}

Финансы

Отзыв не возвращает средства. Аренда и возврат — это раздельные операции: вы оплатили аренду при создании заказа, и досрочный возврат ресурса не отменяет этот платеж.

Ограничение частоты запросов

10 запросов в секунду на один IP.

Коды ошибок

Код	HTTP	Значение
10004	200	Отозвано или уже было отозвано — хеш включен
5003	503	Принято, хеш еще не подтвержден — повторите попытку позже
5005	400	Для этого заказа нечего отзывать
5006	400	Заказ внешнего провайдера — отзыв недоступен
−1	404	Заказ не найден или принадлежит другому аккаунту
−1	401	Ключ API отсутствует или недействителен, либо IP не в белом списке