TRON enerji kiralamasını API ile otomatikleştirmek
Enerji neden otomatik gelmeli
Bir sıcak cüzdan, bir borsa çekim motoru ya da kullanıcılar adına TRC-20 transferi tetikleyen bir sözleşme işletiyorsanız sorunu biliyorsunuz: işlem tetiklendiği anda TRON enerjisi hazır olmalıdır. Enerjiyi bir arayüzden elle yüklemek günde birkaç transferin ötesine ölçeklenmez; pencereyi kaçırırsanız işlem gönderen adresten TRX yakar, çoğu zaman önceden kiralanmış enerjiden çok daha pahalıya.
Çözüm, arka ucunuz bir işlemi yayınlamak üzereyken kiralama API'sini çağırmaktır; enerji kimse müdahale etmeden, programatik olarak gelir.
API zincir üzerinde ne yapar
TRON'un kaynak modeli hesaplamayı (enerji) işlem boyutundan (bandwidth) ayırır. Standart bir USDT TRC-20 transferi, alıcı zaten USDT tutuyorsa yaklaşık 65,000, alıcının USDT bakiyesi sıfırsa yaklaşık 130,000 enerji tüketir: ilk gelen transfer bakiye kaydını oluşturmanın depolama maliyetini öder, dolayısıyla maliyet gönderene değil alıcıya bağlıdır. Bir transferin bandwidth kullanımı yaklaşık 345 bayttır; çoğu hesabın günlük ücretsiz kotası bunu karşılar.
Kiralama API'sini çağırdığınızda servis kendi TRX'ini kilitler ve ortaya çıkan enerjiyi Stake 2.0'ın DelegateResourceContract işlemiyle belirttiğiniz adrese delege eder. Delegasyon adrese özeldir ve süresi sınırlıdır; kiralama süresi dolunca enerji otomatik olarak geri alınır.
Kiralama asenkrondur. API çağrısı hemen bir orderId ve PAID_BY_USER durumuyla döner; zincir üzerindeki delegasyon işlemi arka planda yayınlanır ve genellikle birkaç saniyede zincire yazılır. Entegrasyonunuz ilk yanıtı siparişin kabul edildiğinin ve ödendiğinin onayı olarak almalı, ardından durum ENERGY_DELEGATED olana kadar sipariş ayrıntıları uç noktasını sorgulamalıdır.
Süreyi seçmek
API'nin period parametresi dört değer alır: 1h, 1d, 3d, 30d. Fiyatlar zincir üzerindeki enerji piyasasıyla gün içinde değişir; güncel rakamlar her zaman fiyatlandırma sayfasındadır. Sıralama sabittir: çağrı başına en ucuzu 1h, aynı adresten çok sayıda transfere bölündüğünde en ucuzu 30d.
Giden her transfer için bir kiralama tetikleyen olay odaklı bir sistemde neredeyse her zaman 1h doğru seçimdir: en düşük mutlak bedeli ödersiniz ve enerji, delege edildikten saniyeler sonra harcanır. 1d ve üzeri, gecelik ödeme işi gibi öngörülebilir toplu yükler çalıştırdığınızda ve API'yi onlarca kez çağırmak yerine büyük bir enerji bloğunu bir kez kiralamak istediğinizde mantıklıdır.
Sisteminiz aynı adresten saatte sürekli 20-30'dan fazla transfer tetikliyorsa, beklenen hacme göre boyutlandırılmış bir 1d bloğu kiralamak transfer başına çağrıdan daha temizdir. Peşin maliyet artar, ancak API yükü ve zincir onayı gecikmesi sıcak yoldan çıkar.
Kimlik doğrulama ve istek yapısı
Kiralama uç noktası:
GET https://api.tronenergyrent.com/place-energy-order
Sorgu parametreli düz bir GET isteğidir. Kimlik doğrulama, kayıt olup hesabınıza bakiye yükledikten sonra gösterge panelinden oluşturduğunuz apiKey sorgu parametresidir; başlık tabanlı kimlik doğrulama ya da JSON gövdesi yoktur.
Parametreler:
apiKey(zorunlu): gösterge panelinden aldığınız API anahtarı.period(zorunlu): kiralama süresi,1h,1d,3dya da30d.energyAmount(zorunlu): delege edilecek enerji miktarı, en az15000. Zaten USDT tutan bir alıcıya tek bir standart USDT transferi için65000güvenli değerdir; ilk kez USDT alacak bir adrese transfer için130000kullanın.destinationAddress(zorunlu): enerjiyi alacak TRON adresi (base58check,Tile başlar).preActivateDestinationAddress(isteğe bağlı, varsayılan0): hedef adres hiç TRX almamış, yani zincir üzerinde aktive edilmemişse1yapın. Servis o zaman enerjiyi delege etmeden önce adresi aktive etmek için bakiyenizden1.5 TRXgönderir. Adres zaten aktifse ek bedel ödememek için0bırakın.
Yanıt, sipariş başarılı olsun olmasın her zaman HTTP 200 ile döner; HTTP koduna değil JSON gövdesindeki status alanına göre dallanın. Başarılı gövde:
{
"status": "SUCCESS",
"errorCode": null,
"errorDescription": null,
"requestId": "2651eacd-2428",
"payload": {
"orderId": "128de799-501e-44b2-8d6f-1fa825c2deed",
"totalPriceSun": 5662800,
"totalPriceTrx": 5.6628,
"state": "PAID_BY_USER"
}
}
Hata gövdesinde status: "ERROR", makinece okunabilir bir errorCode ve insan için yazılmış bir errorDescription bulunur:
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
İki durumda da requestId değerini günlüğe yazın; bir kiralamanın peşine düşmek için destekten yardım isterseniz aradıkları kimlik budur.
Sipariş yaşam döngüsü
state alanı küçük ve sabit bir sırayla ilerler:
PAID_BY_USER: başlangıç durumu; sipariş bakiyenizden ödendi, zincir üzerinde henüz işlem yok.WAITING_DELEGATION: servis siparişi aldı, delegasyon işlemini hazırlıyor.ENERGY_DELEGATED: delegasyon zincire yazıldı; hedef adres kiralanan enerjiyi tutuyor ve bir sonraki işlemde harcayabilir.ERROR_DELEGATION: delegasyon başarısız oldu. Nadirdir, yoğun ağ tıkanıklığında görülebilir.CANCELLED: sipariş iptal edildi, bedel bakiyenize iade edildi.
Geçerli durumu görmek için:
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
Yanıt aynı status / errorCode / payload zarfını kullanır; geçerli state, payload içindedir. Siparişten sonra bunu bir-iki saniyede bir sorgulayın ve TRC-20 transferine yalnızca ENERGY_DELEGATED gördükten sonra geçin. Pratikte bir ya da iki sorgu yeter.
Çalışan bir Python örneği
Minimal ama üretim biçiminde bir desen: kiralamayı yapar, delegasyon zincire yazılana kadar sorgular ve bir şey ters giderse açık bir hata verir.
import logging
import time
import requests
API_BASE = "https://api.tronenergyrent.com"
API_KEY = "your_api_key_here"
ENERGY_FOR_TRANSFER = 65_000 # use 130_000 if recipient has zero USDT balance
HTTP_TIMEOUT_SECS = 10
POLL_INTERVAL_SECS = 1
POLL_TIMEOUT_SECS = 30
def place_order(destination_address: str, period: str = "1h",
energy_amount: int = ENERGY_FOR_TRANSFER) -> dict:
resp = requests.get(
f"{API_BASE}/place-energy-order",
params={
"apiKey": API_KEY,
"period": period,
"energyAmount": energy_amount,
"destinationAddress": destination_address,
"preActivateDestinationAddress": 0,
},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"place-energy-order failed: {body.get('errorCode')} "
f"({body.get('errorDescription')}) requestId={body.get('requestId')}"
)
return body["payload"]
def wait_for_delegation(order_id: str) -> dict:
deadline = time.monotonic() + POLL_TIMEOUT_SECS
while time.monotonic() < deadline:
resp = requests.get(
f"{API_BASE}/single-order-details",
params={"apiKey": API_KEY, "orderId": order_id},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"single-order-details failed: {body.get('errorCode')} "
f"({body.get('errorDescription')})"
)
state = body["payload"]["state"]
if state == "ENERGY_DELEGATED":
return body["payload"]
if state == "ERROR_DELEGATION":
raise RuntimeError(f"Delegation failed for order {order_id}")
if state == "CANCELLED":
raise RuntimeError(f"Order {order_id} was cancelled")
time.sleep(POLL_INTERVAL_SECS)
raise TimeoutError(f"Order {order_id} did not reach ENERGY_DELEGATED in {POLL_TIMEOUT_SECS}s")
def rent_energy(destination_address: str) -> dict:
placed = place_order(destination_address)
logging.info(
"Order placed: id=%s priceSun=%s priceTrx=%s",
placed["orderId"], placed["totalPriceSun"], placed["totalPriceTrx"],
)
delegated = wait_for_delegation(placed["orderId"])
logging.info("Order delegated: id=%s", delegated["orderId"])
return delegated
Birkaç nokta. Açık status == "SUCCESS" kontrolü gereklidir, çünkü HTTP kodu her zaman 200'dür ve tek başına resp.raise_for_status() gerçek sonuç hakkında bir şey söylemez. Sorgu döngüsünün sıkı bir zaman aşımı vardır; takılan bir sipariş transfer hattınızı süresiz bloke edemez. state üzerindeki dallanma üç son durumu (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) genel bir "başarılı değil" yaklaşımı yerine açıkça ele alır.
Transfer akışınızda önce rent_energy() fonksiyonunu çağırın, sonra TRC-20 transferini yayınlayın. Sıra önemlidir: önce yayınlarsanız delegasyon henüz zincire yazılmamış olacağı için işlem gönderenden TRX yakar.
Bakiyenizi boyutlandırma
Kiralama bedeli tronenergyrent.com hesabınızdaki bakiyeden düşülür. Bakiye bir eşiğin altına inince uyarı veren ya da otomatik yükleme yapan bir mekanizma kurun; makul bir alt sınır iki saatlik zirve hacmini karşılayan miktardır. Geçerli bakiyeyi programatik okumak için:
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
Yanıt bakiyenizi ve hesap durumunuzu içerir. Bunu izleme yığınınıza bağlayın; gece 2'de bitmiş bir bakiye sizi bir daha şaşırtmaz. tronenergyrent.com bakiyesine en az 10 TRX yüklenebilir.
Hatalarla başa çıkmak
Üretimde en sık üç hata görülür. Kodlar gerçek API'den gelir, güvenle dallanabilirsiniz.
INSUFFICIENT_BALANCE: bakiyeniz istenen kiralamayı ve varsa ön aktivasyonu karşılamıyor. Yeniden denemek çözmez; bunu ayrıca yakalayıp bir uyarı ya da bakiye yükleme akışı tetikleyin verequestIddeğerini uyarıya ekleyin.INVALID_ADDRESS:destinationAddresssunucuda base58check çözümlemesinden geçemedi. Adresleri dinamik olarak, örneğin kullanıcı girdisinden alıyorsanız API'yi çağırmadan önce yerelde doğrulayın;tronpykitaplığında bunun içinis_address()vardır ve hatalı girdiyi istemcide reddetmek gidiş dönüşü beklemekten hızlıdır.INACTIVE_DESTINATION_ADDRESS_ERROR: hedef adres zincir üzerinde aktive edilmemiş ve servisten aktive etmesini istemediniz. Ya adrese başka bir yerden küçük bir miktar TRX gönderin ya da bir sonraki çağrıdapreActivateDestinationAddress=1geçirin; servis adresi1.5 TRXkarşılığında aktive eder.
Daha ince bir durum: aynı hedef için aynı anda kiralama yapan birden fazla işçiniz varsa ORDER_IS_ALREADY_IN_PROGRESS alabilirsiniz. Çözüm API'de değil süreçtedir: hedef adrese göre anahtarlanan ve delegasyon tamamlanana kadar tutulan bir dağıtık kilit (Redis gayet yeter) kullanın.
Zincir üzerinde doğrulama
Çoğu entegrasyon için /single-order-details uç noktasını ENERGY_DELEGATED olana kadar sorgulamak yeterlidir. Ek güvence isterseniz delegasyon zincire yazıldıktan sonra TRON tam düğümünü doğrudan sorgulayabilirsiniz:
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
Yanıt, dış adreslerden delege edilen enerji dahil adresin geçerli kaynak durumunu içerir. Alan adı geçerli Stake 2.0 görünümüne bağlıdır, bu yüzden bağlarken güncel TRON HTTP API belgelerine bakın. Transferi engellemeyen, yalnızca uyarı kaydı düşen yumuşak bir kontrol olarak kullanın: kiralama API'de başarılı görünürken zincir üzerinde başka bir şeyin ters gittiği nadir durumda sizi saatlerce hata ayıklamadan kurtarır.