Energy Reclaim — mengembalikan energy sewaan lebih awal

Mengembalikan energy yang didelegasikan ke pool sebelum periode sewa berakhir. Berguna ketika transaksi tujuan sewa Anda telah terkirim: energy tidak lagi menganggur di alamat, dan pool dapat melayani pihak lain.

Reclaim bersifat sukarela. Masa sewa akan berakhir dengan sendirinya — Anda tidak wajib memanggil endpoint ini.

URL dasar endpoint

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

Bandwidth memiliki endpoint tersendiri, lihat Bandwidth.

Header Permintaan

Header	Wajib	Deskripsi
X-API-KEY	Ya	Kunci API yang digunakan saat membuat pesanan
X-Real-IP	Ya	Alamat IP dari whitelist Anda

user_id Anda diambil dari kunci API — Anda tidak perlu mengirimkannya.

Kunci harus sama dengan yang digunakan untuk pesanan

Pesanan hanya dapat di-reclaim menggunakan kunci yang membuatnya. Kunci berbeda dari akun yang sama tidak akan berfungsi.

---

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

orderId adalah nomor pesanan yang dikembalikan saat energy dipesan — contohnya 1H… untuk sewa 1 jam atau 5M… untuk sewa 5 menit. Tidak ada body permintaan.

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

Respons — berhasil di-reclaim (200, kode 10004)

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

reclaimHash adalah transaksi on-chain yang mengembalikan energy. Waktu umum dari permintaan hingga respons adalah beberapa detik.

Respons — sudah di-reclaim sebelumnya (200, kode 10004)

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

Memanggil endpoint dua kali aman dilakukan: panggilan kedua mengembalikan hash yang sama dan tidak mengubah apa pun. Ini juga mencakup sewa yang sudah kedaluwarsa dengan sendirinya.

Respons — penyedia eksternal (400, kode 5006)

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

Pesanan yang dilayani oleh penyedia eksternal tidak dapat di-reclaim: sumber daya tersebut bukan milik kami untuk dikembalikan. Penyedia mana yang melayani pesanan dapat dilihat pada respons pesanan.

Respons — tidak ada yang perlu di-reclaim (400, kode 5005)

Pesanan tidak pernah menghasilkan pendelegasian, atau pendelegasian sudah tidak aktif. Tidak ada biaya yang dikenakan dan tidak ada yang berubah.

Respons — belum selesai (503, kode 5003)

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

Reclaim telah diterima tetapi transaksi on-chain belum muncul dalam batas waktu tunggu. Kemungkinan besar proses akan selesai dengan sendirinya — ulangi panggilan dalam beberapa detik untuk mendapatkan hash.

Respons — pesanan tidak ditemukan (404)

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

Dikembalikan baik ketika pesanan tidak ada maupun ketika pesanan tersebut milik akun lain.

---

Satu pesanan, bukan satu alamat

Reclaim berfungsi per pesanan, bukan per alamat. Hal ini disengaja: pesanan mengidentifikasi secara tepat apa yang dikembalikan — alamat yang sama dapat menampung energy dari beberapa pesanan, termasuk pesanan dari akun lain.

Dua konsekuensi yang perlu diperhatikan:

• Pesanan massal untuk banyak alamat menghasilkan satu nomor pesanan per alamat. Anda dapat me-reclaim pesanan tersebut secara terpisah; sisanya tetap berjalan.
• Jumlah besar untuk satu alamat mungkin dipecah menjadi beberapa pesanan. Untuk mengosongkan alamat tersebut secara menyeluruh, lakukan reclaim pada masing-masing pesanan.

Me-reclaim pesanan yang dibuat melalui Orchestrator

Bekerja dengan cara yang sama. Tanyakan status permintaan Anda ke Orchestrator, ambil nomor pesanan dari bidang energy.orderIds pada alamat yang Anda inginkan, lalu panggil reclaim dengannya:

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

Biaya

Reclaim tidak mengembalikan dana apa pun. Menyewa dan mengembalikan adalah operasi yang terpisah: Anda telah membayar sewa saat membuat pesanan, dan mengembalikan sumber daya lebih awal tidak membatalkan pembayaran tersebut.

Batas Laju Permintaan

10 permintaan per detik per IP.

Kode Kesalahan

Kode	HTTP	Arti
10004	200	Berhasil di-reclaim, atau sudah di-reclaim sebelumnya — hash disertakan
5003	503	Diterima, hash belum terkonfirmasi — coba lagi segera
5005	400	Tidak ada yang perlu di-reclaim untuk pesanan ini
5006	400	Pesanan penyedia eksternal — reclaim tidak tersedia
−1	404	Pesanan tidak ditemukan, atau milik akun lain
−1	401	Kunci API tidak ada atau tidak valid, atau IP tidak masuk dalam whitelist