POST /apiv2/order5m

Buat pesanan sewa energi 5 menit melalui pool energi internal Netts.

URL Endpoint

POST https://netts.io/apiv2/order5m

Header Permintaan

Header	Diperlukan	Deskripsi
Content-Type	Ya	application/json
X-API-KEY	Ya	Kunci API Anda dari dasbor Netts
X-Real-IP	Ya	Alamat IP dari whitelist Anda

Isi Permintaan

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Parameter Permintaan

Parameter	Tipe	Diperlukan	Deskripsi
amount	integer	Ya	Jumlah Energy yang akan disewa (minimum: 61.000, maksimum: 650.000)
receiveAddress	string	Ya	Alamat TRON yang akan menerima energi (format TRC-20)

Batas Energi

Endpoint 5 menit menerima jumlah energi antara 61.000 dan 650.000 unit per pesanan. Permintaan di luar rentang ini akan ditolak dengan HTTP 400.

Informasi Penyedia

Pesanan energi 5 menit dipenuhi secara eksklusif melalui pool energi internal Netts. Tidak seperti endpoint 1 jam, penyedia eksternal tidak digunakan.

Ketersediaan & Strategi Percobaan Ulang

Karena delegasi hanya berasal dari pool internal, ketidaktersediaan sementara mungkin terjadi selama periode permintaan tinggi. Jika Anda menerima pesan kesalahan 503, coba lagi permintaan setelah jeda singkat atau beralihlah ke endpoint 1 jam yang memiliki akses ke beberapa penyedia eksternal.

Contoh Permintaan

cURL

curl -X POST https://netts.io/apiv2/order5m \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

import requests

url = "https://netts.io/apiv2/order5m"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

Respons

Respons Berhasil (200 OK)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

Berhasil dengan Aktivasi Alamat (200 OK)

Ketika alamat penerima belum diaktifkan di jaringan TRON, Netts akan mengaktifkannya secara otomatis. Biaya aktivasi ditambahkan ke total:

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a"
        }
    }
}

Kolom Respons

Kolom	Tipe	Deskripsi
detail.code	integer	Selalu 10000 untuk pesanan yang berhasil
detail.msg	string	Pesan sukses dengan jumlah yang dipotong
detail.data.orderId	string	ID pesanan terpadu (format: 5M{id})
detail.data.paidTRX	number	Total biaya dalam TRX (termasuk biaya aktivasi jika ada)
detail.data.hash	string	Hash transaksi delegasi
detail.data.delegateAddress	string	Alamat pool yang mendelegasikan energi
detail.data.energy	integer	Jumlah energi + buffer (biasanya +50)
detail.data.activationHash	string	Hanya ada jika aktivasi alamat dilakukan

Respons Kesalahan

Jumlah Energi Tidak Valid (400)

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

Kesalahan Autentikasi (401)

{
    "detail": "Invalid API key or IP not in whitelist"
}

Saldo Tidak Cukup (403)

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

Layanan Tidak Tersedia (503)

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

Menangani Kesalahan 503

Respons 503 berarti pool internal sedang penuh sementara. Strategi yang disarankan:

1. Tunggu 2-3 detik dan coba lagi pesanan 5 menit
2. Jika masih tidak tersedia, beralihlah ke endpoint 1 jam yang menggunakan beberapa penyedia

Kesalahan Server Internal (500)

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

Referensi Kode Kesalahan

Kode	Deskripsi	Status HTTP
10000	Berhasil	200
10000	Berhasil (respons ter-cache)	208
-	Permintaan duplikat masih diproses	409
1003	Jumlah energi di luar rentang	400
1004	Saldo tidak mencukupi	403
1005	Alamat pembayar pengguna belum dikonfigurasi	400
5000	Kesalahan server internal	500
5003	Layanan energi tidak tersedia	503

Batas Kecepatan

Batas laju permintaan berikut berlaku untuk endpoint ini (per alamat IP):

Periode	Batas	Deskripsi
1 detik	50 permintaan	Maksimum 50 permintaan per detik

Header Rate Limit

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

Batas Laju Terlampaui (429)

{
    "message": "API rate limit exceeded"
}

Idempotensi

API mendukung idempotensi untuk mencegah pemrosesan pesanan ganda. Saat Anda mengirim beberapa permintaan identik, sistem memastikan pesanan diproses hanya sekali.

Cara Kerja Idempotensi

Keunikan permintaan ditentukan oleh kombinasi dari:

• Timestamp permintaan (jendela 2 detik)
• Jumlah energi
• Alamat penerima
• Kunci API

Setiap permintaan diberikan jendela keunikan 2 detik. Permintaan dengan parameter yang sama persis dalam jendela ini akan dianggap sebagai duplikat.

Menyediakan Kunci Anda Sendiri

Anda dapat mengelola idempotensi sendiri dengan mengirimkan header X-Idempotency-Key. Jika header ini ada, nilai tersebut saja yang menentukan apakah permintaan merupakan pengulangan, dan kombinasi otomatis di atas tidak digunakan. Jika tidak ada, tidak ada yang berubah — server menghasilkan kunci tersebut untuk Anda.

Aturannya sama seperti pada /apiv2/order1h:

Header	X-Idempotency-Key
Format	Tepat 64 karakter heksadesimal huruf kecil — sebuah digest SHA-256
Masa berlaku	24 jam sejak permintaan pertama yang membawa kunci tersebut
Cakupan	Akun Anda. Nilai yang sama yang dikirim oleh akun berbeda tidak akan pernah mengembalikan hasil Anda

Kunci dalam bentuk lain apa pun — UUID dengan tanda hubung, base64, huruf besar — akan ditolak dengan 400 sebelum pesanan dibuat dan sebelum biaya apa pun dipotong:

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

Turunkan kunci dari kunci API Anda sehingga menjadi unik untuk akun Anda dan dapat dibuat ulang pada upaya percobaan ulang — contoh praktis ada di halaman 1 jam. Sertakan periode sewa dalam pesan yang Anda hash: menyewa alamat yang sama selama 5 menit dan selama 1 jam adalah pesanan yang berbeda, dan menggunakan kembali satu kunci untuk keduanya akan mengembalikan respons pesanan pertama untuk permintaan kedua.

Membuat Dua Pesanan Identik

Jebakan yang sama seperti pada endpoint per jam, dengan jendela waktu yang lebih lebar. Dua pesanan identik — jumlah yang sama ke alamat yang sama — tidak dapat dibedakan dari upaya percobaan ulang, dan hanya waktu kedatangannya yang membedakannya.

Tanpa kunci milik Anda sendiri:

Jeda antara dua permintaan	Apa yang terjadi
Dalam jendela 2 detik yang sama	Permintaan kedua dianggap sebagai pengulangan. Permintaan tidak dieksekusi: Anda menerima 208 dan respons pesanan pertama. Tidak ada biaya yang dikenakan
Lebih dari dua detik terpisah	Dua kunci berbeda — kedua pesanan dibuat dan keduanya dikenakan biaya

Oleh karena itu, beri jeda lebih dari dua detik antara dua pesanan yang identik, dan periksa kode statusnya: 208 berarti pesanan yang baru saja Anda kirim tidak diproses.

Jeda hanyalah solusi sementara, bukan perbaikan menyeluruh — jeda juga memisahkan permintaan yang tidak pernah Anda maksudkan untuk diulang, seperti upaya ulang setelah timeout atau pesan yang dikirim ulang oleh antrean Anda, dan masing-masing menjadi pesanan terpisah dengan biaya terpisah. Mengirimkan kunci Anda sendiri adalah solusi sesungguhnya: nonce baru untuk pesanan baru, nonce percobaan pertama untuk upaya ulang. Penjelasan lengkapnya ada di halaman 1 jam.

Kode Status HTTP untuk Permintaan Duplikat

Kode Status	Nama	Deskripsi
200	OK	Pesanan berhasil diproses (permintaan pertama)
208	Already Reported	Pesanan telah diproses sebelumnya, mengembalikan respons ter-cache
409	Conflict	Permintaan sedang diproses, jangan mencoba lagi

Permintaan Duplikat - Sudah Diproses (208)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

Permintaan Duplikat - Masih Diproses (409)

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "retry_after_seconds": 3
}

Praktik Terbaik

• Jangan mengirim permintaan paralel dengan parameter yang sama - tunggu setiap respons selesai
• Tangani respons 409 dengan menunggu, bukan dengan segera mencoba lagi
• Periksa kolom idempotency.cached untuk mengidentifikasi respons yang ter-cache

Perbandingan: Pesanan 5 Menit vs 1 Jam

Fitur	Pesanan 5 Menit	Pesanan 1 Jam
Endpoint	/apiv2/order5m	/apiv2/order1h
Durasi	5 menit	1 jam
Rentang energi	61.000 - 650.000	61.000 - 3.000.000
Penyedia	Hanya pool internal Netts	Pool internal + penyedia eksternal
Harga	Lebih rendah (tarif 5 menit)	Tarif per jam standar
Ketersediaan	Mungkin terbatas saat beban puncak	Tinggi (tersedia fallback ke beberapa penyedia)
Paling cocok untuk	Transaksi kecil yang sering	Pengiriman besar atau terjamin

Akun Pascabayar

Akun pada penagihan pascabayar menggunakan endpoint, URL, header, dan body permintaan yang sama persis dengan yang lain. Perbedaannya adalah cara pesanan dibayar:

• Tidak ada yang dipotong dari deposit Anda. Setiap pesanan yang berhasil ditambahkan ke saldo terutang akun Anda dalam mata uang penyelesaian yang disepakati dalam kontrak Anda. Anda membayarnya melalui faktur, sesuai dengan perjanjian Anda.
• Akun Anda memiliki batas kredit. Selama jumlah yang terutang masih dalam batas kredit, pesanan akan diterima bahkan dengan deposit nol.
• Hanya layanan yang dikirimkan yang akan ditagih. Pesanan yang ditolak atau tidak dieksekusi tidak dikenakan biaya apa pun.
• Jika alamat penerima perlu diaktifkan, aktivasi tersebut merupakan bagian dari pesanan yang sama dan ditagih sebagai biaya terpisah.

Penagihan pascabayar diaktifkan oleh Netts untuk suatu akun berdasarkan permintaan. Setiap respons memberi tahu Anda bagaimana pesanan dibayar: paymentMode adalah postpaid atau prepaid.

Parameter Tambahan

Parameter	Tipe	Diperlukan	Deskripsi
test	boolean	Tidak	true — hanya menghitung harga. Tidak ada yang dipesan, dikirimkan, atau ditagih
freezePrice	boolean	Tidak	true — mengunci harga berdasarkan kontrak Anda selama 60 detik. Tidak ada yang dipesan atau ditagih
quoteId	string	Tidak	Buat pesanan dengan harga dari penawaran harga yang diterbitkan oleh freezePrice
priceCurrency	string	Tidak	TRX (default) atau mata uang kontrak Anda, seperti dalam settlement.asset. Untuk akun pascabayar, jumlah dalam mata uang kontrak Anda selalu disertakan

quoteId tidak dapat digabungkan dengan test atau freezePrice. Kolom lain apa pun dalam body permintaan akan ditolak.

Pengecekan harga (test: true)

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "test": true
}

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 65000,
            "unitPriceSun": "19",
            "discount": null,
            "energyTRX": "1.235000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "2.335000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.409088", "activation": "0.364370", "total": "0.773458"}},
            "fxAt": "2026-10-19T07:16:12.548894+00:00"
        }
    }
}

Kolom	Deskripsi
unitPriceSun	Harga per unit energi dalam SUN, termasuk diskon pribadi Anda jika ada
discount	Diskon pribadi Anda (type, value) atau null
energyTRX / activationTRX / wouldCostTRX	Energi, aktivasi (jika alamat memerlukannya), dan total, dalam TRX
activationCheck	inactive — alamat akan diaktifkan dan ditagih; active — tidak ada aktivasi; unknown — tidak dapat diperiksa saat ini
alt.<currency>	Jumlah yang sama dalam mata uang kontrak Anda
fxAt	Waktu nilai tukar mata uang yang digunakan untuk jumlah dalam mata uang kontrak Anda

Penawaran harga tetap (freezePrice: true)

Gunakan penawaran harga untuk mengunci harga berdasarkan kontrak Anda sebelum Anda memesan.

1. Kirim pesanan dengan "freezePrice": true. Respons memiliki kode 10011 (Quote issued), kolom yang sama dengan pengecekan harga, ditambah quoteId dan expiresAt.
2. Dalam waktu 60 detik, kirim pesanan dengan "quoteId": "<quoteId>" serta amount dan receiveAddress yang sama.
3. Pesanan ditagih sesuai harga penawaran — harga berdasarkan kontrak Anda pada saat penawaran dibuat — bahkan jika harga berubah di antaranya.

Penawaran harga dapat digunakan sekali dan hanya untuk produk yang sama: penawaran harga 5 menit tidak dapat membayar pesanan 1 jam. Penawaran harga yang kedaluwarsa atau sudah digunakan akan ditolak dan tidak ada yang dipesan.

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "quoteId": "q_4f540f16a2c94b7f8e3d1a6b5c0e9d72"
}

Pesanan berhasil

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.24 TRX service cost, postpaid",
        "data": {
            "orderId": "5M5f557d2fba",
            "paidTRX": 1.235,
            "hash": "c1fafd8ef7fb6b7fb8a729120756b26e611f401275cb4f7a04fe2bafd75b13da",
            "delegateAddress": "TR3qZsdmkFcvP729Md3PwXzktFQkMoUzjg",
            "energy": 65000,
            "paymentMode": "postpaid",
            "energyTRX": "1.235000",
            "activationTRX": "0.000000",
            "totalTRX": "1.235000"
        }
    }
}

Kolom	Deskripsi
paidTRX	Biaya layanan dalam TRX. Untuk akun pascabayar nilai ini tidak dipotong dari deposit
paymentMode	postpaid
energyTRX / activationTRX / totalTRX	Jumlah pasti, 6 tempat desimal
quoteId, alt	Ada ketika pesanan dibuat dengan penawaran harga: ID penawaran harga dan jumlah yang ditawarkan

Semua kolom lainnya sama seperti pada pesanan prabayar.

Batas kredit tercapai (402)

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

Pesanan tidak dieksekusi dan tidak ada yang ditagih. Pesanan baru akan diterima kembali setelah pembayaran Anda terdaftar atau batas kredit Anda dinaikkan.

Kode kesalahan pascabayar

Kode	HTTP	Deskripsi
10010	200	Hasil pengecekan harga (test)
10011	200	Penawaran harga diterbitkan (freezePrice)
1004	402	Batas kredit pascabayar tercapai
4100	400	Permintaan tidak valid
4101	400	priceCurrency tidak didukung
4102	400	quoteId digabungkan dengan test atau freezePrice
4103	409	Penawaran harga sudah digunakan
4104	409	Penawaran harga kedaluwarsa
4105	409	Kunci idempotensi sudah digunakan untuk permintaan lain
4106	404	Penawaran harga tidak ditemukan
4107	409	Parameter pesanan berbeda dari penawaran harga
4108	400	Format quoteId tidak valid
4109	422	Tidak tersedia untuk sub-akun
5032	503	Harga sementara tidak tersedia
5033	503	Nilai tukar sementara tidak tersedia
5034	503	Penagihan sementara tidak tersedia — pesanan tidak diterima
5036	503	Pemeriksaan kredit sementara tidak tersedia — coba lagi nanti

Untuk semua respons 4xx dan 503 di atas, tidak ada yang dipesan dan tidak ada yang ditagih.

Catatan

• Energy dikirimkan secara instan setelah pesanan berhasil (biasanya dalam 0,5-2 detik)
• Batas waktu respons API: Maksimum 10 detik (termasuk upaya percobaan ulang internal)
• Aktivasi alamat: Jika alamat penerima belum diaktifkan, Netts mengaktifkannya sesuai harga modal. Biaya aktivasi hanya dikenakan sekali per alamat
• Durasi: Tetap 5 menit (300 detik)
• Jumlah minimum energi: 61.000 unit
• Jumlah maksimum energi: 650.000 unit per pesanan
• Buffer energi: +50 unit ditambahkan secara otomatis (gratis)
• Format ID pesanan: 5M{id} untuk pelacakan terpadu
• Harga: Dinamis berdasarkan waktu dalam sehari melalui Pricing API
• Batas laju permintaan: 50 permintaan per detik per alamat IP
• Hanya pool internal: Jika pool sedang penuh, coba lagi setelah jeda singkat atau gunakan endpoint 1 jam sebagai cadangan fallback