Bir TRON enerji API'si aslında ne yapar?
Bir TRON enerji API'si tek bir şey satar ve bu, bir ücretteki indirim değildir. Hesabınızın USDT sözleşmesini çalıştırmak için enerjiye ihtiyacı vardır; enerji yoksa ağ bunun yerine TRX alır, birim başına 100 sun. Bir enerji API'si, TRX stake etmiş başka bir hesabın kendi enerjisini birkaç dakikalığına transferinizi imzalayacak adrese ödünç vermesini ayarlar. Aşağıdaki her şey, zincirdeki bu tek olgunun etrafına dizilen isteklerin biçimidir.
Zincirde bu bir devirdir ve hiçbir yerini siz imzalamazsınız
Ödünç veren hesap, adresinizi anan bir devir imzalar. Sizin adresiniz hiçbir şey imzalamaz, hiçbir şeyi onaylamaz ve karşılığında hiçbir yetki vermez: ağ o adresin enerji limitini yükseltir ve olayın tamamı bundan ibarettir (enerji nedir). Bir enerji API'sinin adres istemesinin, anahtar hiç istememesinin sebebi de budur — bu mekanizmadaki tek imza karşı tarafa aittir.
İşleyen en küçük akış
Temel adres https://api.nrg.market/v1, anahtar ise tek bir başlıkla gider: Authorization: Bearer nrg_live_…. Anahtar oluşturulurken bir kez gösterilir ve bir IP listesine sabitlenebilir. Çağrıyı kendi sunucunuzdan yapın: kimlik doğrulamalı uç noktalar hiçbir tarayıcı kaynağına izin vermez, çünkü bir sayfaya ulaşan anahtar herkesin anahtarıdır. İkinci bir temel adres daha var, nrg.market'in sandbox alt alan adında — aynı /v1 yüzeyinin test parası ve benzetilmiş bir zincir üzerindeki hâli, kendi nrg_test_… anahtarları ve kendi paneliyle; belgeleri docs.nrg.market'te.
POST /v1/estimate ile başlayın. Hiçbir şey ayırmaz, hiçbir şey tahsil etmez, tek çağrıda 500 alıcıya kadar alır ve bir siparişin hesaplayacağı şeyi döndürür.
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}
# kısaltıldı — yanıt ayrıca kalem başına price_trx, total_trx ve burn_cost_trx taşır
kind, zaten USDT tutan bir alıcı için single, tutmayan ve önce bir jeton hesabı açılması gereken alıcı için double, bir sözleşme için ise custom olur; sonuncusu iki standart rakamdan değil, bir deneme çalıştırmasından fiyatlanır. from isteğe bağlıdır ve fiyatı kımıldatmaz; onu vermek, gönderen hakkında iki yanıt satın alır — warnings içindeki inactive_sender ve blacklisted_sender — kullandığınız moddaki bir sipariş bunlardan biri yüzünden geri çevirmeden önce.
Sonra sipariş. Mode a, transferi kendinizin yayınladığı moddur.
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"}]}'
Yanıt 202'dir ve kendiniz kurmak yerine okumaya değer iki başlık taşır: siparişin kendi adresi olan Location ve ilk sorgudan önce ve sorgular arasında beklenecek saniyeyi veren Retry-After. Gövde siparişin kendisidir; normalde status funded, send_before ise hâlâ null olur — para ayrılmıştır ve satın alma başlamıştır.
send_before, enerji zincirde onaylanıp sipariş ready durumuna geldiğinde görünür. Son onaylanan devirden sayılan, yaklaşık dört dakikalık bir penceredir; bu yüzden toplu bir siparişin bütün kalemleri tek bir son ana ortaktır. Dört dakikayı varsaymak yerine alanı okuyun. Yine ready sözcüğünü değil, o alanın görünmesini kollayın: mode A'daki bir sipariş sizin transferinizle değil enerjinin teslimiyle yerine getirilir, dolayısıyla completed siz daha hiçbir şey göndermeden gelebilir.
İlk canlı siparişten önce iki reddi bağlamaya değer: para kımıldamadan önce karara bağlanan ve required_trx ile available_trx taşıyan 402 insufficient_balance, bir de details.reason alanı inactive_wallet olan 422 invalid_address — gönderen cüzdan hiç aktive edilmemiştir, dolayısıyla enerjinin devredileceği bir hesap yoktur (bunların arkasındaki başarısızlıklar).
İdempotentlik anahtarı
POST /v1/orders bir Idempotency-Key ister ve bu anahtar, ayrıştırılmış JSON'a değil gövdenin ham baytlarına bağlıdır. Aynı baytlar size özgün siparişi geri verir; aynı anahtar altındaki başka bir gövde ikinci bir sipariş değil 409 idempotency_conflict olur; doğrulamanın geri çevirdiği bir istek anahtarı harcamaz. Toplu boyutta bir ağ zaman aşımını yanıtı olan bir soruya çeviren şey budur.
Hız limiti başlıkları size ne söyler
API anahtarı başına üç kova sayılır: dakikada 120 sipariş, 600 referans isteği ve 60 GET /v1/address-check — çünkü onun önbelleğini ıskalayan her istek zincire sorulmuş bir sorudur. Anahtarla sayılan bir kovadan gelen her yanıt, başarılı olanlar dâhil, RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset taşır; böylece bir istemci reddi aldıktan sonra değil, ondan önce yavaşlayabilir. Limit aşıldığında yanıt Retry-After ile birlikte 429 rate_limited olur. Bir başka 429 ise neredeyse bunun tersini anlatır: too_many_auth_failures geldiğinde beklemek işe yaramaz, çünkü geri çevrilen kimlik bilgisinin kendisidir. Dallanmayı code üzerinden yapın, asla message üzerinden değil.
Webhooks, döngü bir sorgulama olmasın diye
Bir alıcıyı POST /v1/webhooks ile kaydedin: url https olmalı, herkese açık bir makineye çözülmeli ve içinde kimlik bilgisi taşımamalıdır. İmzalama sırrı yalnızca oluşturma anında bir kez döner ve bir hesap en fazla beş etkin uç nokta tutar. Akışın neye ihtiyacı varsa ona abone olun — order.ready, order.completed, order.partially_completed, order.failed, bir de kalem bazındaki order.item.sent ve order.item.expired. Her teslimat X-NRG-Timestamp, X-NRG-Event-Id ve zaman damgası, bir nokta ve ham gövde üzerinden alınmış bir HMAC-SHA256 olan X-NRG-Signature taşır: doğrulamayı yeniden kodladığınız JSON'a göre değil, aldığınız baytlara göre yapın ve yinelenenleri event_id üzerinden ayıklayın. POST /v1/webhooks/{webhook_id}/test, gerçek yolun üzerinden gerçek ve imzalı bir teslimat gönderir ve uç noktanızın ne yanıtladığını bildirir; bunun hiçbir bedeli yoktur.
Mode B: siz imzalarsınız, yayını biz yaparız
Mode b, from ve to yerine imzalanmış işlemin onaltılık hâlini taşıyan signed_tx alanını koyar; enerji iner inmez yayını biz yaparız — dört dakikalık bir pencerenin başında kimse oturup beklemez. Kabul edilenin dar tutulması kasıtlıdır: USDT sözleşmesinin bir transfer çağrısı ve başka hiçbir şey, tek bir sahip imzası, ekli TRX yok ve çok imzalı hesap kabul edilmez — bir yetkinin anahtar takımı zincirde yaşar ve bizim haberimiz olmadan değişebilir. İşlemin, sipariş oluşturulurken önünde üç dakikalık ömrü kalmış olmalıdır ve kendi son kullanma anı pencereyi kısaltır: send_before hiçbir zaman o son anı, bir yayın payı düşülmüş hâliyle, aşmaz. Zamanında iletemezsek kalem broadcast_window_missed ile failed olarak kapanır, rezerv olduğu gibi geri döner.
Mode C: alıcı adı verilmeden enerji
Mode c, from ve kind alır, alıcıyı hiç almaz — toplu iş daha ortada yokken hazır olmasını istediğiniz bir cüzdan için. kind ya single ya double olur ve doğrusunu bulmak size düşer: alıcı olmadığı için hacmi okuyacak bir yer yoktur, dolayısıyla double gerekirken verilen single transferi eksik bırakır ve aradaki fark TRX yakar. custom burada bilerek sunulmaz; o, belirli bir sözleşme alıcısına karşı yapılan bir deneme çalıştırmasının sonucudur. Kalemler to: null taşır, hiçbir zaman sent olmaz ve pencere kapanınca expired olur: kira süresi dolmuştur, ki bu bir başarısızlık değil olağan sondur — ve enerji teslim edildiği için ücretlendirilir.
İstekte hiçbir zaman bulunmayan şey
Sözleşmenin hiçbir yerinde, hiçbir modda özel anahtara ait bir alan yoktur. Mode A işleminizi hiç görmez. Mode B zaten imzaladığınız bir işlemi görür ve o imzayı bozmadan tek bir baytını bile değiştiremeyiz; işlem şifreli tutulur ve sipariş nihai bir duruma ulaştıktan yedi gün sonra silinir. Mode C'nin görebileceği bir işlem yoktur. API'ye verilen şey adreslerdir (neyi tutup neyi tutmadığımızın geri kalanı).
Anahtar istemeyen kısımlar
Referans uç noktaları ve sözleşme hiç anahtar istemez; limitleri anahtar başına değil IP başına sayılır. GET /v1/tariff, bir enerji biriminin şu andaki fiyatını sun cinsinden, çalışan dilimi, next_change_at alanını ve bir referans takvimini yanıtlar — fiyatlar sayfasının her açılışta okuduğu şey budur. GET /v1/market, izlediğimiz satıcıların kendileri için yayımladıklarını yanıtlar; her rakam okunduğu anla damgalıdır ve kendi fiyatımız da aralarında sıralanır — piyasa sayfası budur. Bir sayıyı değil uç noktayı alıntılayın: bizim fiyatımız birkaç dakikada bir yeniden hesaplanır.
Sözleşmenin kendisi https://docs.nrg.market/openapi.yaml adresinde durur, bayt bayt aynısı da https://api.nrg.market/v1/contract.yaml adresinde — bilmeye değer, çünkü belge sunucusu, bazı programatik istemcileri istek bize ulaşmadan geri çeviren bir kenar katmanının arkasındadır. Oradaki ETag gövdenin SHA-256'sıdır, dolayısıyla hiçbir şey değişmediğinde If-None-Match bir 304 alır. İstemcinizi o dosyadan üretin: bu sayfa bir özettir, bağlı olduğumuz şey ise dosyadır.