POST /apiv2/order5m
Netts dahili enerji havuzları aracılığıyla 5 dakikalık bir enerji kiralama siparişi oluşturun.
Uç Nokta URL'si
POST https://netts.io/apiv2/order5mİstek Üstbilgileri
| Header | Required | Description |
|---|---|---|
| Content-Type | Yes | application/json |
| X-API-KEY | Yes | Netts panelinizdeki API anahtarınız |
| X-Real-IP | Yes | Beyaz listenizdeki IP adresi |
İstek Gövdesi
{
"amount": 65000,
"receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}İstek Parametreleri
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | integer | Yes | Kiralanacak Energy miktarı (minimum: 61.000, maksimum: 650.000) |
| receiveAddress | string | Yes | Enerjiyi alacak TRON adresi (TRC-20 formatında) |
Energy Limitleri
5 dakikalık endpoint, sipariş başına 61.000 ile 650.000 birim arasındaki enerji miktarlarını kabul eder. Bu aralığın dışındaki istekler HTTP 400 ile reddedilecektir.
Sağlayıcı Bilgileri
5 dakikalık enerji siparişleri yalnızca Netts dahili enerji havuzları aracılığıyla karşılanır. 1 saatlik endpoint'in aksine, harici sağlayıcılar kullanılmaz.
Kullanılabilirlik ve Yeniden Deneme Stratejisi
Delegasyonlar yalnızca dahili havuzlardan sağlandığından, talebin yüksek olduğu dönemlerde geçici olarak hizmet verilemeyebilir. Bir 503 hatası alırsanız, kısa bir süre sonra isteği yeniden deneyin veya birden fazla harici sağlayıcıya erişimi olan 1 saatlik endpoint'e geçiş yapın.
Örnekler
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:
# Havuz geçici olarak kullanılamıyor - yeniden deneyin veya 1 saate geçin
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)}")Yanıt
Başarılı Yanıt (200 OK)
{
"detail": {
"code": 10000,
"msg": "Successful, 1.430 TRX deducted",
"data": {
"orderId": "5Mb4ee11ef86",
"paidTRX": 1.43,
"hash": "3636f97dde244fca17cdc0b2cf7fd1572a9b4c6d8e0f1a3b5c7d9e1f3a5b7c9d",
"delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
"energy": 65050
}
}
}Adres Etkinleştirmeli Başarılı Yanıt (200 OK)
Alıcı adresi TRON ağında etkinleştirilmediğinde, Netts bunu otomatik olarak etkinleştirir. Etkinleştirme maliyeti toplama eklenir:
{
"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"
}
}
}Yanıt Alanları
| Field | Type | Description |
|---|---|---|
| detail.code | integer | Başarılı siparişler için her zaman 10000 |
| detail.msg | string | Düşülen tutarı belirten başarı mesajı |
| detail.data.orderId | string | Birleşik sipariş kimliği (format: 5M{id}) |
| detail.data.paidTRX | number | TRX cinsinden toplam maliyet (varsa etkinleştirme ücretini içerir) |
| detail.data.hash | string | Delegasyon işlem karması (hash) |
| detail.data.delegateAddress | string | Enerjiyi delege eden havuz adresi |
| detail.data.energy | integer | Energy miktarı + tampon (genellikle +50) |
| detail.data.activationHash | string | Yalnızca adres etkinleştirmesi yapıldığında mevcuttur |
Hata Yanıtları
Geçersiz Energy Miktarı (400)
{
"code": 1003,
"msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}Kimlik Doğrulama Hatası (401)
{
"detail": "Invalid API key or IP not in whitelist"
}Yetersiz Bakiye (403)
{
"code": 1004,
"msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}Hizmet Kullanılamıyor (503)
{
"code": 5003,
"msg": "Service temporarily unavailable. Energy delegation failed after retries."
}503 Hatalarının Yönetimi
Bir 503 yanıtı, dahili havuzların geçici olarak tam kapasiteye ulaştığı anlamına gelir. Önerilen strateji:
- 2-3 saniye bekleyin ve 5 dakikalık siparişi yeniden deneyin
- Hâlâ kullanılamıyorsa, birden fazla sağlayıcı kullanan 1 saatlik endpoint'e geçiş yapın
Sunucu İçi Hata (500)
{
"code": 5000,
"msg": "Internal server error occurred"
}Hata Kodu Referansı
| Code | Description | HTTP Status |
|---|---|---|
10000 | Başarılı | 200 |
10000 | Başarılı (önbelleğe alınmış yanıt) | 208 |
- | Yinelenen istek hâlâ işleniyor | 409 |
1003 | Energy miktarı aralık dışında | 400 |
1004 | Yetersiz bakiye | 403 |
1005 | Kullanıcı ödeme adresi yapılandırılmamış | 400 |
5000 | Sunucu içi hata | 500 |
5003 | Enerji hizmeti kullanılamıyor | 503 |
İstek Hızı Sınırları
Bu endpoint için aşağıdaki istek sınırları geçerlidir (IP adresi başına):
| Period | Limit | Description |
|---|---|---|
| 1 saniye | 50 istek | Saniyede maksimum 50 istek |
İstek Hızı Sınırı Üstbilgileri
RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49İstek Sınırı Aşıldı (429)
{
"message": "API rate limit exceeded"
}Eşgüçlülük (Idempotency)
API, yinelenen sipariş işlemlerini önlemek için eşgüçlülüğü (idempotency) destekler. Birden fazla özdeş istek gönderdiğinizde, sistem siparişin yalnızca bir kez işlenmesini sağlar.
Eşgüçlülük Nasıl Çalışır?
İstek benzersizliği aşağıdakilerin birleşimi ile belirlenir:
- İstek zaman damgası (2 saniyelik pencere)
- Energy miktarı
- Alıcı adresi
- API anahtarı
Her isteğe 2 saniyelik bir benzersizlik penceresi tanınır. Bu pencere içinde aynı parametrelere sahip istekler yinelenen olarak kabul edilir.
Kendi Anahtarınızı Belirtme
X-Idempotency-Key üstbilgisini göndererek eşgüçlülüğü kendi kontrolünüze alabilirsiniz. Bu üstbilgi mevcut olduğunda, bir isteğin tekrar olup olmadığına yalnızca bu değer karar verir ve yukarıdaki otomatik kombinasyon kullanılmaz. Bulunmadığında ise hiçbir şey değişmez; sunucu anahtarı sizin için türetir.
Kurallar /apiv2/order1h üzerindeki kurallarla aynıdır:
| Header | X-Idempotency-Key |
| Format | Tam olarak 64 küçük harfli onaltılık karakter — bir SHA-256 özeti |
| Ömür | Bu anahtarı taşıyan ilk istekten itibaren 24 saat |
| Kapsam | Hesabınız. Farklı bir hesap tarafından gönderilen aynı değer asla sizin sonucunuzu döndürmez |
Başka herhangi bir biçimdeki anahtar — tireli UUID, base64, büyük harfli onaltılık — sipariş verilmeden ve herhangi bir ücret alınmadan önce 400 ile reddedilir:
{
"detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}Anahtarı API anahtarınızdan türeterek hesabınıza özel ve yeniden denemelerde tekrarlanabilir olmasını sağlayın — işlenmiş örnek 1 saatlik sayfasında yer almaktadır. Kiralama süresini özetlediğiniz mesaja dahil edin: aynı adresi 5 dakika ve 1 saat kiralamak farklı siparişlerdir ve her ikisi için tek bir anahtarın yeniden kullanılması, ikinci istek için ilk siparişin yanıtını döndürür.
İki Özdeş Sipariş Verme
Saatlik endpoint ile aynı tuzak, sadece daha geniş bir pencereye sahiptir. İki özdeş sipariş — aynı adrese aynı miktar — yeniden denemeden ayırt edilemez ve onları yalnızca varış anı ayırır.
Kendi anahtarınız olmadan:
| İki istek arasındaki süre | Ne olur |
|---|---|
| Aynı 2 saniyelik pencere içinde | İkinci istek bir tekrar olarak algılanır. Yürütülmez: 208 ve ilk siparişin yanıtını alırsınız. Bunun için hiçbir ücret alınmaz |
| İki saniyeden daha uzun aralıkla | İki farklı anahtar — her iki sipariş de verilir ve her ikisi de ücretlendirilir |
Bu nedenle, iki özdeş sipariş arasında iki saniyeden fazla süre bırakın ve durum kodunu kontrol edin: 208, az önce gönderdiğiniz siparişin verilmediği anlamına gelir.
Bekleme yapmak geçici bir çözümdür, kalıcı bir çözüm değildir; zaman aşımından sonra yeniden deneme veya kuyruğunuz tarafından yeniden iletilen bir mesaj gibi asla tekrarlamak istemediğiniz istekleri de ayırır ve bunların her biri ayrı bir ücretle ayrı bir sipariş haline gelir. Kendi anahtarınızı göndermek durumu kesin olarak çözer: yeni bir sipariş için yeni bir nonce, yeniden deneme için ilk girişimin nonce değeri. Mantığın tamamı 1 saatlik sayfasında yer almaktadır.
Yinelenen İstekler İçin HTTP Durum Kodları
| Status Code | Name | Description |
|---|---|---|
| 200 | OK | Sipariş başarıyla işlendi (ilk istek) |
| 208 | Already Reported | Sipariş zaten işlenmişti, önbelleğe alınmış yanıt döndürülüyor |
| 409 | Conflict | İstek şu anda işleniyor, yeniden denemeyin |
Yinelenen İstek - Zaten İşlendi (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"
}
}Yinelenen İstek - Hâlâ İşleniyor (409)
{
"success": false,
"error": "duplicate_request_processing",
"message": "This request is currently being processed. Please wait and do not retry.",
"retry_after_seconds": 3
}En İyi Uygulamalar
- Aynı parametrelerle paralel istekler göndermeyin - her yanıtı bekleyin
- 409 yanıtlarını hemen yeniden denemek yerine bekleyerek yönetin
- Önbelleğe alınmış yanıtları belirlemek için
idempotency.cachedalanını kontrol edin
Karşılaştırma: 5 Dakikalık ve 1 Saatlik Siparişler
| Feature | 5-Minute Order | 1-Hour Order |
|---|---|---|
| Endpoint | /apiv2/order5m | /apiv2/order1h |
| Süre | 5 dakika | 1 saat |
| Energy aralığı | 61.000 - 650.000 | 61.000 - 3.000.000 |
| Sağlayıcılar | Yalnızca Netts dahili havuzları | Dahili havuzlar + harici sağlayıcılar |
| Fiyat | Daha düşük (5 dakikalık tarife) | Standart saatlik tarife |
| Kullanılabilirlik | Yoğun zamanlarda sınırlı olabilir | Yüksek (çoklu sağlayıcı yedeklemesi) |
| En uygun kullanım | Sık ve küçük işlemler | Büyük veya garantili teslimat |
Faturalı (Postpaid) Hesaplar
Faturalı ödeme kullanan hesaplar, diğer herkesle aynı endpoint, URL, başlıklar ve istek gövdesini kullanır. Fark, siparişin nasıl ödendiğindedir:
- Depozitonuzdan hiçbir şey düşülmez. Başarılı her sipariş, sözleşmenizde kararlaştırılan ödeme para biriminde hesap bakiyenize borç olarak eklenir. Sözleşmenize uygun olarak fatura karşılığı ödersiniz.
- Hesabınızın bir kredi limiti vardır. Ödenmesi gereken tutar limit dahilinde olduğu sürece, sıfır depozitoyla bile siparişler kabul edilir.
- Yalnızca teslim edilen hizmetler faturalandırılır. Reddedilen veya yürütülmeyen bir sipariş hiçbir ücrete tabi değildir.
- Alıcı adresin etkinleştirilmesi gerekiyorsa, etkinleştirme aynı siparişin bir parçasıdır ve ayrı bir ücret olarak faturalandırılır.
Faturalı ödeme, talep üzerine Netts tarafından bir hesap için etkinleştirilir. Her yanıt, siparişin nasıl ödendiğini bildirir: paymentMode, postpaid veya prepaid şeklindedir.
Ek istek alanları
| Parameter | Type | Required | Description |
|---|---|---|---|
| test | boolean | No | true — yalnızca fiyatı hesaplar. Hiçbir şey sipariş edilmez, teslim edilmez veya faturalandırılmaz |
| freezePrice | boolean | No | true — sözleşmeniz kapsamındaki fiyatı 60 saniye boyunca sabitler. Hiçbir şey sipariş edilmez veya faturalandırılmaz |
| quoteId | string | No | Siparişi freezePrice tarafından verilen teklifin fiyatıyla verir |
| priceCurrency | string | No | TRX (varsayılan) veya settlement.asset içinde belirtildiği gibi sözleşmenizin para birimi. Faturalı hesaplar için sözleşme para biriminizdeki tutarlar her zaman dahil edilir |
quoteId, test veya freezePrice ile birleştirilemez. İstek gövdesindeki diğer tüm alanlar reddedilir.
Fiyat kontrolü (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"
}
}
}| Field | Description |
|---|---|
| unitPriceSun | Varsa kişisel indiriminiz dahil, SUN cinsinden enerji birim fiyatı |
| discount | Kişisel indiriminiz (type, value) veya null |
| energyTRX / activationTRX / wouldCostTRX | TRX cinsinden Energy, etkinleştirme (adres gerektiriyorsa) ve toplam tutar |
| activationCheck | inactive — adres etkinleştirilecek ve faturalandırılacaktır; active — etkinleştirme yok; unknown — şu anda kontrol edilemedi |
alt.<currency> | Sözleşmenizin para birimindeki aynı tutarlar |
| fxAt | Sözleşme para biriminizdeki tutarlar için kullanılan döviz kurunun zamanı |
Sabit fiyat teklifi (freezePrice: true)
Sipariş vermeden önce sözleşmeniz kapsamındaki fiyatı sabitlemek için bir teklif kullanın.
- Siparişi
"freezePrice": trueile gönderin. Yanıt10011koduna (Quote issued), fiyat kontrolüyle aynı alanlara, artıquoteIdveexpiresAtalanlarına sahiptir. - 60 saniye içinde siparişi
"quoteId": "<quoteId>"ve aynıamountvereceiveAddressile gönderin. - Sipariş, bu arada fiyat değişse bile teklif edilen fiyattan — teklif anında sözleşmeniz kapsamındaki fiyattan — faturalandırılır.
Bir teklif bir kez ve yalnızca aynı ürün için kullanılabilir: 5 dakikalık bir teklif, 1 saatlik bir siparişi ödeyemez. Süresi dolmuş veya zaten kullanılmış bir teklif reddedilir ve hiçbir şey sipariş edilmez.
{
"amount": 65000,
"receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
"quoteId": "q_4f540f16a2c94b7f8e3d1a6b5c0e9d72"
}Başarılı sipariş
{
"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"
}
}
}| Field | Description |
|---|---|
| paidTRX | Hizmetin TRX cinsinden maliyeti. Faturalı hesaplar için depozitodan düşülmez |
| paymentMode | postpaid |
| energyTRX / activationTRX / totalTRX | Kesin tutarlar, 6 ondalık basamak |
| quoteId, alt | Sipariş bir teklif ile verildiğinde mevcuttur: teklif kimliği ve teklif edilen tutarlar |
Diğer tüm alanlar ön ödemeli (prepaid) siparişlerle aynıdır.
Kredi limitine ulaşıldı (402)
{
"detail": {
"code": 1004,
"msg": "Postpaid credit limit reached.",
"paymentMode": "postpaid",
"reason": "limit_reached"
}
}Sipariş yürütülmez ve hiçbir şey faturalandırılmaz. Ödemeniz kaydedildiğinde veya limitiniz artırıldığında yeni siparişler tekrar kabul edilir.
Faturalı hata kodları
| Code | HTTP | Description |
|---|---|---|
10010 | 200 | Fiyat kontrolü sonucu (test) |
10011 | 200 | Teklif verildi (freezePrice) |
1004 | 402 | Faturalı kredi limitine ulaşıldı |
4100 | 400 | Geçersiz istek |
4101 | 400 | Desteklenmeyen priceCurrency |
4102 | 400 | quoteId, test veya freezePrice ile birleştirilmiş |
4103 | 409 | Teklif zaten kullanılmış |
4104 | 409 | Teklifin süresi dolmuş |
4105 | 409 | Eşgüçlülük anahtarı farklı bir istek için zaten kullanılmış |
4106 | 404 | Teklif bulunamadı |
4107 | 409 | Sipariş parametreleri tekliften farklı |
4108 | 400 | Geçersiz quoteId formatı |
4109 | 422 | Alt hesaplar için kullanılamaz |
5032 | 503 | Fiyat geçici olarak kullanılamıyor |
5033 | 503 | Döviz kuru geçici olarak kullanılamıyor |
5034 | 503 | Faturalandırma geçici olarak kullanılamıyor — sipariş kabul edilmedi |
5036 | 503 | Kredi kontrolü geçici olarak kullanılamıyor — daha sonra tekrar deneyin |
Yukarıdaki tüm 4xx ve 503 yanıtları için hiçbir şey sipariş edilmez ve hiçbir şey faturalandırılmaz.
Notlar
- Enerji, sipariş başarılı olduğunda anında teslim edilir (genellikle 0,5-2 saniye içinde)
- API yanıt zaman aşımı: Maksimum 10 saniye (dahili yeniden deneme girişimlerini içerir)
- Adres etkinleştirme: Alıcı adresi etkinleştirilmemişse Netts bunu maliyet fiyatına etkinleştirir. Etkinleştirme ücreti adres başına yalnızca bir kez alınır
- Süre: Sabit 5 dakika (300 saniye)
- Minimum enerji miktarı: 61.000 birim
- Maksimum enerji miktarı: Sipariş başına 650.000 birim
- Energy tamponu: Otomatik olarak +50 birim eklenir (ücretsiz)
- Sipariş kimliği formatı: Birleşik izleme için
5M{id} - Fiyatlandırma: Pricing API aracılığıyla günün saatine göre dinamik
- İstek sınırlaması: IP adresi başına saniyede 50 istek
- Yalnızca dahili havuzlar: Havuzlar tam kapasitedeyse, kısa bir süre sonra tekrar deneyin veya alternatif olarak 1 saatlik endpoint'i kullanın