POST /apiv2/bandwidth

TRON Bandwidth kiralayın ve sabit bir süre için (5 dakika veya 1 saat) alıcı bir adrese delege edin.

⚠️ Erişim seviyeleri.
Akredite hesaplar, havuz boyutu ve maksimum limitler dahilinde herhangi bir miktarı (5000'e kadar), birden fazla eşzamanlı siparişle kiralayabilir. Akreditasyon Netts desteği tarafından verilir.
Akreditasyon olmadan, bir defaya mahsus 400 birim kiralayabilirsiniz — bir sonraki siparişe yalnızca önceki kiralama sona erdikten sonra izin verilir. 400 dışındaki miktarlar için yapılan istekler veya ilki hâlâ etkinken verilen ikinci bir sipariş reddedilir.

Uç Nokta URL'si

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

İstek Başlıkları

Başlık	Zorunlu	Açıklama
Content-Type	Evet	application/json
X-API-KEY	Evet	Netts kontrol panelinden alınan API anahtarınız
X-Real-IP	Evet	Beyaz listenizdeki IP adresi
X-Idempotency-Key	Hayır	Çift sipariş vermeden güvenli bir şekilde yeniden denemek için isteğe bağlı istemci tarafından oluşturulan anahtar (base64). Belirtilmezse, sunucu otomatik olarak bir tane oluşturur

İstek Gövdesi

json

{
    "amount": 1500,
    "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "period": "5m"
}

Parametreler

Parametre	Tür	Zorunlu	Açıklama
amount	integer	Evet	Kiralanacak Bandwidth birimi (minimum: 400, maksimum: 5000)
receiveAddress	string	Evet	Bandwidth alacak TRON adresi (`T…`, 34 karakter, base58)
period	string	Evet	Kiralama süresi: `"5m"` (5 dakika) veya `"1h"` (1 saat)
trx_send	boolean	Hayır	Garantili işlem: Bandwidth mevcut değilse, işlemin yine de gerçekleşmesi için adrese TRX gönderin. Yalnızca `amount = 400` olduğunda çalışır (aksi takdirde yoksayılır). Varsayılan `false`
check	boolean	Hayır	`true` ise ve alıcının zaten 400'den fazla Bandwidth değeri varsa, sipariş delege edilmez ve hiçbir ücret alınmaz (`enough` durumu). Varsayılan `false`
test	boolean	Hayır	Kuru çalışma (dry run). `true` ise, tüm sipariş akışı simüle edilir — yanıt size zincir üzerinde herhangi bir işlem yapmadan ve ücretlendirme olmadan gerçekleşecek sonucu ve tahsil edilecek fiyatı bildirir. Varsayılan `false`

Örnek İstekler

Aşağıdaki örnekler ayrıca X-Idempotency-Key oluşturur ve gönderir, böylece yanlışlıkla yapılan bir tekrarlama ikinci bir sipariş oluşturmaz. Tüm kurallar için Idempotency bölümüne bakın.

cURL

bash

API_KEY="your_api_key"
ADDR="TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AMOUNT=1500
PERIOD="5m"
NONCE=$(( $(date +%s) / 2 ))   # stable for retries within a 2s window; or your own order UUID

# X-Idempotency-Key = base64( HMAC-SHA256( API_KEY, "addr:amount:period:nonce" ) )
IDEMP=$(printf '%s' "${ADDR}:${AMOUNT}:${PERIOD}:${NONCE}" \
  | openssl dgst -sha256 -hmac "$API_KEY" -binary | base64)

curl -X POST https://netts.io/apiv2/bandwidth \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: $IDEMP" \
  -d "{\"amount\": $AMOUNT, \"receiveAddress\": \"$ADDR\", \"period\": \"$PERIOD\"}"

Python

python

import time, hmac, hashlib, base64, requests

API_KEY = "your_api_key"
url = "https://netts.io/apiv2/bandwidth"
payload = {
    "amount": 1500,
    "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "period": "5m",
}

# X-Idempotency-Key = base64( HMAC-SHA256( API_KEY, "addr:amount:period:nonce" ) )
# Generate ONCE per order and resend the same value on every retry.
nonce = str(int(time.time() // 2))   # 2s bucket; or your own order UUID
message = f"{payload['receiveAddress']}:{payload['amount']}:{payload['period']}:{nonce}"
idem_key = base64.b64encode(
    hmac.new(API_KEY.encode(), message.encode(), hashlib.sha256).digest()
).decode()

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Real-IP": "your_whitelisted_ip",
    "X-Idempotency-Key": idem_key,
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
detail = data.get("detail", {})

if response.status_code == 200 and detail.get("status") == "completed":
    d = detail["data"]
    print(f"Order ID: {d['orderId']}")
    print(f"Hashes:   {d['hash']}")          # array of delegation tx hashes
    print(f"Bandwidth: {d['bandwidth']} for {d['period']}")
    print(f"Cost:     {d['paidTRX']} TRX")
else:
    print(f"Code: {detail.get('code')} | {detail.get('msg', detail)}")

Hizmet paketiyle birlikte tam bir istemci örneği (Python + cURL) sağlanmaktadır (handler_bandwidth/doc/client_example/).

Yanıt

Başarılı — Bandwidth delege edildi (200 OK)

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful",
        "data": {
            "orderId": "B5M<key14>",
            "paidTRX": "<amount charged in TRX>",
            "fulfilledBy": "bandwidth",
            "hash": ["a1b2c3...", "d4e5f6..."],
            "bandwidth": 1500,
            "period": "5m"
        }
    }
}

Başarılı — Bandwidth yerine TRX gönderildi (200 OK, yalnızca `amount=400` + `trx_send=true`)

Havuzda Bandwidth bulunmadığında ve trx_send etkinleştirildiğinde, işlemin yine de gerçekleşmesi için adrese TRX gönderilir. Bu durumda, talep edilen süreye bakılmaksızın sabit bir ücret uygulanır.

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful (sent TRX, bandwidth unavailable)",
        "data": {
            "orderId": "B5M<key14>",
            "paidTRX": "<amount charged in TRX>",
            "fulfilledBy": "trx",
            "trxSendHash": ["<txid>"],
            "hash": [],
            "bandwidth": 400,
            "period": "5m"
        }
    }
}

Zaten yeterli — ücret alınmadı (200 OK, yalnızca `check=true` ile)

json

{
    "detail": {
        "code": 10002,
        "status": "enough",
        "msg": "enough band for 1 transfer",
        "data": { "orderId": "B5M<key14>", "paidTRX": 0, "bandwidth": 400, "period": "5m" }
    }
}

İşleniyor — harici sağlayıcı (202 Accepted)

Sipariş eşzamansız olarak harici bir sağlayıcıya devredildiğinde döndürülür. Tamamlanana kadar orderId kullanarak durum uç noktasını (aşağıda) sorgulayın (poll edin).

json

{
    "detail": {
        "code": 10001,
        "status": "processing",
        "msg": "Order accepted, processed by an external provider. Poll the status endpoint.",
        "data": { "orderId": "B5M<key14>", "bandwidth": 1500, "period": "5m" }
    }
}

Test çalıştırması (200 OK, yalnızca `test=true` ile)

Tüm sipariş akışı simüle edilir. testAction neyin gerçekleşeceğini ve wouldCostTRX ne kadar ücretlendirileceğini bildirir. Hiçbir şey delege edilmez, TRX gönderilmez, hiçbir ücret alınmaz (paidTRX: 0).

json

{
    "detail": {
        "code": 10003,
        "status": "test",
        "msg": "Test run — no on-chain action, no charge",
        "data": {
            "orderId": "B5M<...>",
            "testAction": "would_delegate",
            "wouldCostTRX": "<amount that would be charged in TRX>",
            "paidTRX": 0,
            "bandwidth": 400,
            "period": "5m",
            "receiverFreeBandwidth": 600
        }
    }
}

testAction değerleri: would_delegate (Bandwidth delege edilecek), would_trx_send (Bandwidth yok, amount=400 + trx_send → TRX gönderilecek), enough (alıcıda zaten yeterli var, check=true ile) veya would_error:<reason> (ör. no_bandwidth, not_whitelisted).

Yanıt Alanları

Alan	Tür	Açıklama
detail.code	integer	`10000` delege edildi/TRX, `10002` yeterli, `10001` işleniyor
detail.status	string	`completed` / `enough` / `processing` / `failed`
detail.data.orderId	string	Sipariş Kimliği, biçim `B5M…` (5m) / `B1H…` (1h) — durum uç noktası için bunu kullanın
detail.data.paidTRX	number	TRX cinsinden tahsil edilen tutar (`enough` durumunda `0`)
detail.data.fulfilledBy	string	`bandwidth` (delege edildi) / `trx` (TRX gönderildi)
detail.data.hash	array	Delegasyon işlem hash'leri (10'a kadar). Her zaman bir dizi (TRX dalı için boştur)
detail.data.trxSendHash	array	TRX transfer hash('leri), yalnızca `fulfilledBy = trx` olduğunda mevcuttur
detail.data.bandwidth	integer	Delege edilen Bandwidth birimleri
detail.data.period	string	Kiralama süresi (`5m` / `1h`)

Durum Uç Noktası

GET https://netts.io/apiv2/bandwidth/status/{orderId}

Başlıklar: X-API-KEY + X-Real-IP (sipariş kimliği doğrulanmış kullanıcıya ait olmalıdır).

Sipariş durumu	HTTP	code	status
Tamamlandı	200	10000	`completed` (`hash` / `trxSendHash` ile)
Devam ediyor	200	10001	`processing`
Zaten yeterli	200	10002	`enough`
Başarısız oldu	200	5003	`failed`
Bulunamadı / size ait değil	404	-1	—

Geri Alma (Reclaim) Uç Noktası

Süresi dolmadan önce delege edilmiş siparişlerinizden birinin Bandwidth değerini isteğe bağlı olarak geri alın (delegasyonu kaldırın). Bandwidth delegasyonu otomatik olarak kaldırılır ve işlem hash'i döndürülür.

POST https://netts.io/apiv2/bandwidth/reclaim/{orderId}

Başlıklar: X-API-KEY + X-Real-IP (sipariş kimliği doğrulanmış kullanıcıya ait olmalıdır).

Sipariş durumu	HTTP	code	status	Sonuç
Delege edildi → şimdi geri alındı	200	10004	`reclaimed`	`reclaimHash` (delegasyon kaldırma işlem hash'leri)
Zaten geri alındı	200	10004	`reclaimed`	`reclaimHash` + "already reclaimed" mesajı
Delege edilmiş durumda değil (geri alınacak bir şey yok)	400	5005	`failed`	—
Geri alma işlemi henüz tamamlanmadı	503	5003	`failed`	kısa süre içinde tekrar deneyin
Bulunamadı / size ait değil	404	-1	—	—

bash

curl -X POST https://netts.io/apiv2/bandwidth/reclaim/B5M<...> \
  -H "X-API-KEY: your_api_key" -H "X-Real-IP: your_whitelisted_ip"

json

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Bandwidth reclaimed",
        "data": { "orderId": "B5M<...>", "reclaimHash": ["<txid>"] }
    }
}

python

import requests

order_id = "B5M..."   # the orderId from your rental response
url = f"https://netts.io/apiv2/bandwidth/reclaim/{order_id}"
headers = {"X-API-KEY": "your_api_key", "X-Real-IP": "your_whitelisted_ip"}

resp = requests.post(url, headers=headers)
detail = resp.json()["detail"]

if resp.status_code == 200 and detail["status"] == "reclaimed":
    print(f"Reclaimed: {detail['data']['reclaimHash']} ({detail['msg']})")
else:
    print(f"Code {detail.get('code')}: {detail.get('msg', detail)}")

Kiralama ücreti, isteğe bağlı erken geri alma durumunda iade edilmez — geri alma işlemi yalnızca delege edilen Bandwidth değerini süresinden önce havuza iade eder.

Hata Yanıtları

Kimlik Doğrulama Hatası (401)

json

{ "detail": { "code": -1, "msg": "Invalid API key or IP not in whitelist" } }

Yetersiz Bakiye (403)

json

{ "detail": { "code": 1004, "status": "failed", "msg": "Insufficient funds" } }

Doğrulama Hatası (400)

json

{ "detail": { "code": 5004, "status": "failed", "msg": "Bandwidth amount out of range (400..5000)" } }

Delegasyon Başarısız Oldu / Hizmet Kullanılamıyor (503)

json

{ "detail": { "code": 5003, "status": "failed", "msg": "Bandwidth delegation failed" } }

Hata Kodu Referansı

Kod	Açıklama	HTTP Durumu
`10000`	Başarılı (delege edildi veya TRX gönderildi)	200
`10000`	Başarılı (önbelleğe alınmış yanıt)	208
`10001`	Kabul edildi, harici sağlayıcı tarafından işleniyor	202
`10002`	Alıcının zaten yeterli Bandwidth değeri var (ücretlendirilmedi)	200
`10003`	Test çalıştırması — sonuç + fiyat önizlemesi, hiçbir şey ücretlendirilmedi (`test=true`)	200
`10004`	Bandwidth geri alındı (isteğe bağlı delegasyon kaldırma) — `reclaimHash` döndürüldü	200
`-`	Yinelenen istek hâlâ işleniyor	409
`-1`	Geçersiz API anahtarı / IP beyaz listede değil	401
`1004`	Yetersiz bakiye	403
`1005`	Kullanıcı için ödeme yapan adresi yok	400
`5004`	Geçersiz miktar/süre (doğrulama)	400
`5005`	Geri alınacak bir şey yok (sipariş delege edilmiş bir durumda değil)	400
`5007`	Akreditasyon olmadan — aynı anda yalnızca bir kiralama; önceki sipariş hâlâ aktif (bitene kadar bekleyin)	503
`5008`	Akreditasyon olmadan — yalnızca 400 birimlik siparişlere izin verilir; daha büyük miktarlar için akreditasyon gereklidir	503
`5003`	Bandwidth delegasyonu başarısız oldu / kullanılamıyor	503
`5000`	Dahili sunucu hatası	500

Hız Limitleri

Süre	Limit	Açıklama
1 saniye	50 istek	IP başına saniyede maksimum 50 istek

Hız Limiti Aşıldı (429)

json

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

Idempotency

Yanlışlıkla yapılan bir tekrarlamanın ikinci bir sipariş oluşturmaması için isteğe bağlı X-Idempotency-Key başlığını gönderin — orijinal yanıt HTTP 208 ile döndürülür. Başlığı göndermezseniz, sunucu kısa bir zaman aralığında istek parametrelerinizden otomatik olarak bir anahtar türetir.

Anahtar nasıl oluşturulur

Anahtar base64( HMAC-SHA256( secret, message ) ) şeklindedir — 44 karakterlik bir base64 dizesidir, burada:

secret = API anahtarınız (X-API-KEY);
message = : ile birleştirilmiş alanlar — receiveAddress:amount:period:nonce.

nonce, aynı mantıksal siparişin yeniden denemeleri arasında kararlı, ancak farklı siparişler arasında farklı olan herhangi bir değerdir — ör. bu sipariş için tuttuğunuz bir UUID veya kaba bir zaman damgası aralığı. Anahtarı sipariş başına bir kez oluşturun ve her yeniden denemede tam olarak aynı değeri yeniden gönderin.

python

import hmac, hashlib, base64, time

def make_idempotency_key(api_key, receive_address, amount, period, nonce=None):
    if nonce is None:
        nonce = str(int(time.time() // 2))   # 2-second bucket; or your own order UUID
    message = f"{receive_address}:{amount}:{period}:{nonce}"
    digest = hmac.new(api_key.encode(), message.encode(), hashlib.sha256).digest()
    return base64.b64encode(digest).decode()  # 44-char base64

bash

# then send it as a header:
-H "X-Idempotency-Key: <base64_key>"

İletiye period bilgisinin dahil edilmesi önemlidir: aynı adresi 5m ve 1h için kiralamak farklı siparişlerdir ve farklı anahtarlar üretmelidir.

Doğrulama. Sağlanan bir X-Idempotency-Key, 16–64 karakterden oluşan bir base64 dizesi olmalıdır (karakter kümesi A–Z a–z 0–9 + / = _ -). Hatalı biçimlendirilmiş veya aşırı uzun bir anahtar HTTP 400 (code 5004) ile reddedilir.

Durum Kodu	Anlamı
200	Başarıyla işlendi (ilk istek)
208	Zaten başarıyla işlendi — önbelleğe alınmış yanıt döndürüldü (ikinci ücretlendirme yok)
409	Aynı istek şu anda işleniyor — bekleyin, henüz yeniden denemeyin

Bir hatadan sonra yeniden deneme. Yalnızca başarılı sonuçlar (completed / enough) önbelleğe alınır. Önceki deneme başarısız olduysa veya zaman aşımına uğradıysa (hiçbir ücret alınmadı), güvenle aynı X-Idempotency-Key ile yeniden deneyebilirsiniz — eski hatayı döndürmek yerine sipariş yeniden denenir. Bir deneme hâlâ devam ederken 409 alırsınız; bekleyin ve yeniden deneyin.

Notlar

Erişim seviyeleri: Akredite hesaplar, eşzamanlı siparişlerle havuz/maksimum limitler dahilinde herhangi bir miktarı kiralayabilir; akreditasyon olmadan — bir defaya mahsus 400 birim (bir sonraki sipariş yalnızca önceki kiralama sona erdikten sonra). Akreditasyon için Netts desteğiyle iletişime geçin.
Minimum: 400 birim. Maksimum: sipariş başına 5000 birim (mevcut yapılandırma).
Süreler: 5m (300 sn) ve 1h (3600 sn). Bandwidth, süre sona erdiğinde otomatik olarak geri alınır.
Tampon yok: tam olarak talep edilen miktar delege edilir.
hash bir dizidir: tek bir sipariş 10 adede kadar delegasyon hash'i üretebilir — tümü döndürülür.
Fiyatlandırma: talep edilen miktar ve süreye göre TRX cinsinden tahsil edilir; oranlar günün saatine göre değişebilir. Güncel fiyatlandırma için destek ekibiyle iletişime geçin.
Küçük sipariş telafisi (delegasyon): 1000 birimin altındaki siparişler için, zincir üzerindeki delegasyon ve geri alma işleminin telafisi olarak fiyata sabit 0.372 TRX eklenir. 1000 birim veya daha fazla olan siparişlerde böyle bir ekleme yapılmaz.
TRX gönderme telafisi: sipariş TRX gönderilerek karşılandığında (fulfilledBy = trx), bunun yerine sabit 0.268 TRX eklenir (zincir üzerindeki TRX transferinin telafisi).
trx_send: yalnızca amount = 400 için geçerlidir; Bandwidth mevcut değilse, işlemin yine de gerçekleşmesi için adrese TRX gönderilir.
check: alıcı zaten 400'den fazla Bandwidth değerine sahip olduğunda delegasyonu (ve ücretlendirmeyi) atlar.
Sipariş Kimliği biçimi: B5M… (5 dakika) / B1H… (1 saat).
Yanıt zaman aşımı: delegasyon beklenirken ~12 saniyeye kadar; genellikle 1–2 saniye.

POST /apiv2/bandwidth ​

Uç Nokta URL'si ​

İstek Başlıkları ​

İstek Gövdesi ​

Parametreler ​

Örnek İstekler ​

cURL ​

Python ​

Yanıt ​

Başarılı — Bandwidth delege edildi (200 OK) ​

Başarılı — Bandwidth yerine TRX gönderildi (200 OK, yalnızca amount=400 + trx_send=true) ​

Zaten yeterli — ücret alınmadı (200 OK, yalnızca check=true ile) ​

İşleniyor — harici sağlayıcı (202 Accepted) ​

Test çalıştırması (200 OK, yalnızca test=true ile) ​

Yanıt Alanları ​

Durum Uç Noktası ​

Geri Alma (Reclaim) Uç Noktası ​

Hata Yanıtları ​

Kimlik Doğrulama Hatası (401) ​

Yetersiz Bakiye (403) ​

Doğrulama Hatası (400) ​

Delegasyon Başarısız Oldu / Hizmet Kullanılamıyor (503) ​

Hata Kodu Referansı ​

Hız Limitleri ​

Hız Limiti Aşıldı (429) ​

Idempotency ​

Anahtar nasıl oluşturulur ​

Notlar ​

POST /apiv2/bandwidth

Uç Nokta URL'si

İstek Başlıkları

İstek Gövdesi

Parametreler

Örnek İstekler

cURL

Python

Yanıt

Başarılı — Bandwidth delege edildi (200 OK)

Başarılı — Bandwidth yerine TRX gönderildi (200 OK, yalnızca `amount=400` + `trx_send=true`)

Zaten yeterli — ücret alınmadı (200 OK, yalnızca `check=true` ile)

İşleniyor — harici sağlayıcı (202 Accepted)

Test çalıştırması (200 OK, yalnızca `test=true` ile)

Yanıt Alanları

Durum Uç Noktası

Geri Alma (Reclaim) Uç Noktası

Hata Yanıtları

Kimlik Doğrulama Hatası (401)

Yetersiz Bakiye (403)

Doğrulama Hatası (400)

Delegasyon Başarısız Oldu / Hizmet Kullanılamıyor (503)

Hata Kodu Referansı

Hız Limitleri

Hız Limiti Aşıldı (429)

Idempotency

Anahtar nasıl oluşturulur

Notlar