Apa yang sebenarnya dilakukan API energi TRON
API energi TRON menjual satu hal, dan hal itu bukan potongan atas sebuah biaya. Akun Anda butuh energi untuk menjalankan kontrak USDT, dan tanpa energi jaringan mengambil TRX sebagai gantinya, 100 sun untuk tiap unit. Sebuah API energi mengatur agar akun lain — akun yang sudah melakukan staking TRX — meminjamkan energinya kepada alamat yang akan menandatangani transfer Anda, selama beberapa menit. Semua yang ada di bawah ini adalah bentuk permintaan di sekeliling satu fakta on-chain itu.
Di rantai ini sebuah delegasi, dan Anda tidak menandatangani apa pun di dalamnya
Akun yang meminjamkan menandatangani sebuah delegasi yang menyebut alamat Anda. Alamat Anda tidak menandatangani apa pun, tidak menyetujui apa pun, dan tidak memberikan apa pun sebagai balasan: jaringan menaikkan batas energinya, dan hanya itulah seluruh peristiwanya (apa itu energi). Karena itulah sebuah API energi meminta alamat dan tidak pernah meminta kunci — satu-satunya tanda tangan dalam pengaturan ini milik pihak sebelah sana.
Alur terkecil yang bekerja
URL dasarnya https://api.nrg.market/v1 dan kuncinya berjalan di satu header, Authorization: Bearer nrg_live_…. Kunci itu ditampilkan sekali saja ketika diterbitkan dan bisa dipatok ke sebuah daftar IP. Panggil dari server Anda: endpoint yang meminta autentikasi sama sekali tidak mengizinkan origin peramban, sebab kunci yang sampai ke halaman adalah kunci yang dipegang semua orang. Ada URL dasar kedua, di subdomain sandbox milik nrg.market — permukaan /v1 yang sama di atas uang uji dan rantai simulasi, dengan kunci nrg_test_…-nya sendiri dan panel akunnya sendiri, dan itu didokumentasikan di docs.nrg.market.
Mulailah dengan POST /v1/estimate. Ia tidak mencadangkan apa pun dan tidak menagih apa pun, menerima sampai 500 penerima dalam satu panggilan, dan mengembalikan apa yang akan dihitung oleh sebuah pesanan.
curl -s https://api.nrg.market/v1/estimate \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"duration_s":300,
"transfers":[{"from":"TQ5NMqJjW8sBGqcpvUcXhbXm3jGnyDCmwK",
"to":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"}]}'
{"items":[{"to":"TN3W…","kind":"single","energy_units":65000,"warnings":[]}],
"zone":"day","duration_s":300}
# dipangkas — jawabannya juga membawa price_trx per posisi, total_trx dan burn_cost_trx
kind bernilai single untuk penerima yang sudah memegang USDT, double untuk yang belum dan perlu dibuatkan akun token lebih dulu, dan custom untuk sebuah kontrak, yang dihitung harganya dari dry-run alih-alih dari salah satu angka baku itu. from bersifat opsional dan tidak menggeser harga; menyertakannya membeli dua jawaban tentang pengirim — inactive_sender dan blacklisted_sender di antara warnings — sebelum sebuah pesanan di mode yang Anda pakai menolak karena salah satunya.
Lalu pesanannya. Mode a adalah mode ketika Anda sendiri yang menyiarkan transfernya.
curl -s https://api.nrg.market/v1/orders \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: 8f3c1e02-6b47-4a1d-9d5c-0b2e7c4a1f90" \
-d '{"mode":"a","client_ref":"invoice-1042",
"transfers":[{"from":"TQ5NMqJjW8sBGqcpvUcXhbXm3jGnyDCmwK",
"to":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"}]}'
Jawabannya 202 dengan dua header yang lebih baik dibaca daripada dirakit sendiri: Location, URL pesanan itu sendiri, dan Retry-After, jumlah detik untuk menunggu sebelum polling pertama dan di antara polling. Body-nya adalah pesanan itu, biasanya dengan status di funded dan send_before masih null — uangnya sudah dicadangkan dan pembeliannya sudah berjalan.
send_before muncul ketika energinya terkonfirmasi di rantai dan pesanannya mencapai ready. Itu jendela sekitar empat menit, dihitung dari delegasi terkonfirmasi yang terakhir, jadi tiap posisi dalam satu pesanan massal berbagi satu tenggat; bacalah field-nya, jangan menganggap empat menit itu pasti. Pantau munculnya field itu, bukan kata ready, juga: pesanan di mode A dipenuhi oleh pengiriman energi dan bukan oleh transfer Anda, jadi completed bisa datang sebelum Anda mengirim apa pun.
Dua penolakan layak disiapkan sebelum pesanan sungguhan yang pertama: 402 insufficient_balance, yang diputuskan sebelum uang bergerak dan membawa required_trx serta available_trx, dan 422 invalid_address dengan details.reason bernilai inactive_wallet — dompet pengirimnya tidak pernah diaktifkan, jadi tidak ada akun yang bisa menerima delegasi (kegagalan di balik keduanya).
Kunci idempotensi
POST /v1/orders mewajibkan Idempotency-Key, dan kunci itu terikat pada byte mentah dari body, bukan pada JSON yang sudah diurai. Byte yang sama mengembalikan pesanan yang asli; body yang berbeda dengan kunci yang sama adalah 409 idempotency_conflict dan bukan pesanan kedua; permintaan yang ditolak validasi tidak menghabiskan kuncinya. Pada ukuran pesanan massal justru itulah yang mengubah timeout jaringan menjadi pertanyaan yang punya jawaban.
Apa yang diberitahukan header batas laju
Tiga kuota dihitung untuk tiap kunci API: pesanan 120 per menit, permintaan rujukan 600, dan GET /v1/address-check 60, sebab tiap kali cache-nya meleset itu satu pertanyaan ke rantai. Tiap jawaban dari kuota yang terikat kunci, termasuk yang berhasil, membawa RateLimit-Limit, RateLimit-Remaining dan RateLimit-Reset, jadi klien bisa memperlambat diri sebelum penolakan datang, bukan sesudahnya; melewati batas, jawabannya 429 rate_limited dengan Retry-After. Ada satu 429 lain yang artinya hampir kebalikannya — too_many_auth_failures, dan di situ menunggu tidak menolong karena kredensialnya sendiri yang ditolak. Bercabanglah pada code, jangan pernah pada message.
Webhooks, supaya loop-nya bukan polling
Daftarkan penerima dengan POST /v1/webhooks: url-nya harus https, mengarah ke host publik dan tidak membawa kredensial. Secret penandatanganannya dikembalikan sekali saja, saat pembuatan, dan satu akun memegang paling banyak lima endpoint aktif. Berlanggananlah pada apa yang dibutuhkan alur Anda — order.ready, order.completed, order.partially_completed, order.failed, ditambah order.item.sent dan order.item.expired yang per posisi. Tiap pengiriman membawa X-NRG-Timestamp, X-NRG-Event-Id dan X-NRG-Signature, sebuah HMAC-SHA256 atas stempel waktu, sebuah titik dan body mentahnya: verifikasi terhadap byte yang Anda terima, bukan terhadap JSON yang Anda susun ulang, dan buang duplikat berdasarkan event_id. POST /v1/webhooks/{webhook_id}/test menjatuhkan satu pengiriman bertanda tangan yang sungguhan lewat jalur yang sebenarnya dan melaporkan apa yang dijawab endpoint Anda, tanpa biaya.
Mode B: Anda yang menandatangani, kami yang menyiarkan
Mode b mengganti from dan to dengan signed_tx, transaksi yang sudah ditandatangani dalam bentuk hex, dan kami menyiarkannya begitu energinya mendarat — tidak ada siapa pun yang duduk menunggui jendela empat menit. Apa yang diterima memang sengaja sempit: satu panggilan transfer pada kontrak USDT dan tidak yang lain, satu tanda tangan pemilik, tanpa TRX yang ikut dikirim, dan multisig ditolak, karena susunan kunci sebuah permission hidup di rantai dan bisa berubah tanpa kami ketahui. Transaksinya harus punya sisa umur tiga menit ketika pesanan dibuat, dan masa berlakunya sendiri memperpendek jendelanya — send_before tidak pernah melewati tenggat itu dikurangi margin penyiaran. Gagal merelainya tepat waktu, posisinya ditutup failed dengan broadcast_window_missed, cadangannya kembali utuh.
Mode C: energi tanpa penerima yang disebut
Mode c menerima from dan kind tanpa penerima sama sekali — untuk dompet yang ingin Anda siapkan sebelum kiriman massalnya ada. kind bernilai single atau double, dan Andalah yang harus menetapkannya dengan benar: tanpa penerima tidak ada apa pun yang bisa dibaca untuk menentukan volumenya, jadi single di tempat yang butuh double membuat transfernya kurang dan selisihnya membakar TRX. custom sengaja tidak ditawarkan di sini, sebab ia adalah hasil dry-run terhadap satu penerima kontrak tertentu. Posisi membawa to: null, tidak pernah mencapai sent, dan menjadi expired ketika jendelanya tutup: masa sewanya habis, dan itu akhir yang normal alih-alih sebuah kegagalan — dan tetap ditagih, karena energinya sudah terkirim.
Apa yang tidak pernah ada di dalam permintaan
Tidak ada field untuk kunci privat di mana pun dalam kontrak ini, di mode mana pun. Mode A tidak pernah melihat transaksi Anda. Mode B melihat transaksi yang sudah Anda tandatangani, yang tidak bisa kami ubah satu byte pun tanpa merusak tanda tangan itu; ia disimpan terenkripsi dan dihapus tujuh hari setelah pesanannya final. Mode C tidak punya transaksi untuk dilihat. Yang diberikan kepada API adalah alamat (selebihnya soal apa yang kami pegang dan tidak kami pegang).
Bagian yang tidak butuh kunci
Endpoint rujukan dan kontraknya sama sekali tidak butuh kunci, dan lajunya dibatasi per IP alih-alih per kunci. GET /v1/tariff menjawab harga satu unit energi dalam sun saat ini, zona yang sedang berjalan, next_change_at dan sebuah jadwal rujukan — itulah yang dibaca halaman harga pada tiap kali muat. GET /v1/market menjawab apa yang dipublikasikan para pemasok yang kami pantau tentang diri mereka sendiri, tiap angka bertanda saat ia dibaca dan harga kami sendiri diperingkat di antaranya, dan itulah halaman pasar. Kutiplah endpoint-nya, bukan angkanya: harga kami dihitung ulang setiap beberapa menit.
Kontraknya sendiri ada di https://docs.nrg.market/openapi.yaml, dan dokumen yang sama byte demi byte ada di https://api.nrg.market/v1/contract.yaml — layak diketahui, sebab host dokumentasi berada di balik edge yang menolak sebagian klien program sebelum permintaannya sampai ke kami. ETag di sana adalah SHA-256 dari body-nya, jadi If-None-Match mendapat 304 ketika tidak ada yang berubah. Bangkitkan klien Anda dari berkas itu: halaman ini ringkasan, dan berkas itulah yang mengikat kami.