ब्लॉग · 7 सितंबर 2026

TRON ऊर्जा API असल में करता क्या है

TRON ऊर्जा API एक ही चीज़ बेचता है, और वह किसी फ़ीस पर छूट नहीं है। USDT अनुबंध चलाने के लिए आपके खाते को ऊर्जा चाहिए, और वह न हो तो नेटवर्क उसकी जगह TRX ले लेता है, हर इकाई के लिए 100 sun। ऊर्जा API का काम इतना है कि किसी दूसरे खाते से — ऐसे खाते से जिसने TRX स्टेक कर रखा है — कुछ मिनटों के लिए उसकी ऊर्जा उस पते को उधार दिला दे जो आपके ट्रांसफ़र पर हस्ताक्षर करेगा। नीचे जो कुछ है, वह चेन पर घटी इसी एक बात के इर्द-गिर्द बने अनुरोधों का ढाँचा है।

चेन पर यह ऊर्जा सौंपना है, और उसमें आपका कोई हस्ताक्षर नहीं

उधार देने वाला खाता आपके पते का नाम लेकर ऊर्जा सौंपने पर हस्ताक्षर करता है। आपका पता न कुछ हस्ताक्षर करता है, न कुछ मंज़ूर करता है, न बदले में कुछ देता है: नेटवर्क उसकी ऊर्जा-सीमा बढ़ा देता है, और पूरी घटना बस इतनी है (ऊर्जा है क्या)। इसीलिए ऊर्जा API एक पता माँगता है, कुंजी कभी नहीं — इस पूरे इंतज़ाम में इकलौता हस्ताक्षर दूसरी तरफ़ का है।

सबसे छोटा फ़्लो जो चलता है

बेस URL https://api.nrg.market/v1 है और कुंजी एक ही हेडर में जाती है, Authorization: Bearer nrg_live_…। जारी होते समय वह एक ही बार दिखती है, और उसे IP की एक सूची से बाँधा जा सकता है। इसे अपने सर्वर से बुलाइए: प्रमाणित एंडपॉइंट किसी भी ब्राउज़र ऑरिजिन को नहीं मानते, क्योंकि जो कुंजी किसी पन्ने तक पहुँच गई वह सबकी कुंजी है। एक दूसरा बेस URL भी है, nrg.market के एक sandbox सबडोमेन पर — वही /v1 सतह, पर टेस्ट पैसे और सिम्युलेटेड चेन पर, अपनी nrg_test_… कुंजियों और अपने अलग कैबिनेट के साथ; उसके दस्तावेज़ docs.nrg.market पर हैं।

शुरुआत POST /v1/estimate से कीजिए। यह न कुछ रोकता है न कुछ काटता है, एक ही कॉल में 500 तक प्राप्तकर्ता लेता है, और वही लौटाता है जो कोई ऑर्डर गिनता।

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}
# छाँटा हुआ — जवाब में हर आइटम का price_trx, total_trx और burn_cost_trx भी आते हैं

जिस प्राप्तकर्ता के पास पहले से USDT है उसके लिए kind single होता है; जिसके पास नहीं है और जिसका टोकन खाता पहले बनाना पड़ेगा, उसके लिए double; और किसी अनुबंध के लिए custom, जिसकी क़ीमत दोनों मानक आँकड़ों से नहीं, एक ड्राई-रन से निकलती है। from वैकल्पिक है और क़ीमत ज़रा नहीं हिलाता; उसे देने से भेजने वाले के बारे में दो जवाब मिल जाते हैं — inactive_sender और blacklisted_sender, दोनों warnings के भीतर — उससे पहले कि आप जिस मोड में हैं उसका ऑर्डर इन्हीं में से किसी पर मना कर दे।

फिर ऑर्डर। a वह मोड है जिसमें ट्रांसफ़र आप ख़ुद प्रसारित करते हैं।

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"}]}'

जवाब 202 आता है, और उसके दो हेडर ख़ुद जोड़ने के बजाय पढ़ने लायक़ हैं: Location, यानी ऑर्डर का अपना URL, और Retry-After, यानी पहली बार पूछने से पहले और दो बार पूछने के बीच कितने सेकंड रुकना है। बॉडी में ऑर्डर होता है, आम तौर पर status funded पर और send_before अब भी null — पैसा रोक लिया गया है और ख़रीद शुरू हो चुकी है।

send_before तब आता है जब ऊर्जा चेन पर पक्की हो जाती है और ऑर्डर ready तक पहुँचता है। यह लगभग चार मिनट की अवधि है, जो ऊर्जा सौंपे जाने की आख़िरी पुष्टि से गिनी जाती है, इसलिए एक बैच के हर आइटम की समय-सीमा एक ही होती है; चार मिनट मान लेने के बजाय वही फ़ील्ड पढ़िए। और ready शब्द के बजाय भी उसी फ़ील्ड पर नज़र रखिए: mode A का ऑर्डर ऊर्जा पहुँचाने से पूरा होता है, आपके ट्रांसफ़र से नहीं, इसलिए completed तब भी आ सकता है जब आपने कुछ भेजा ही न हो।

पहले लाइव ऑर्डर से पहले दो अस्वीकृतियाँ जोड़ रखना ठीक रहता है: 402 insufficient_balance, जो पैसा हिलने से पहले ही तय हो जाती है और required_trx तथा available_trx साथ लाती है, और 422 invalid_address, जिसमें details.reason inactive_wallet पर होता है — भेजने वाला वॉलेट कभी सक्रिय हुआ ही नहीं, इसलिए ऊर्जा सौंपने को कोई खाता ही नहीं है (इनके पीछे की नाकामियाँ)।

idempotency कुंजी

POST /v1/orders के लिए Idempotency-Key ज़रूरी है, और वह पार्स किए हुए JSON से नहीं, बॉडी के कच्चे बाइट से बँधी होती है। वही बाइट दोबारा भेजने पर वही पहला ऑर्डर वापस मिलता है; उसी कुंजी के साथ दूसरी बॉडी 409 idempotency_conflict है, दूसरा ऑर्डर नहीं; और जाँच में लौटाया गया अनुरोध कुंजी ख़र्च नहीं करता। बैच के आकार पर यही चीज़ नेटवर्क के टाइमआउट को ऐसे सवाल में बदल देती है जिसका जवाब मौजूद है।

rate-limit हेडर आपको क्या बताते हैं

हर API कुंजी पर तीन बकेट गिने जाते हैं: ऑर्डर एक मिनट में 120, संदर्भ अनुरोध 600, और GET /v1/address-check 60 — क्योंकि उसके कैश से चूका हर सवाल चेन तक जाता है। कुंजी वाले बकेट का हर जवाब, कामयाब जवाब भी, RateLimit-Limit, RateLimit-Remaining और RateLimit-Reset लाता है, ताकि क्लाइंट मना होने के बाद नहीं, उससे पहले धीमा हो सके; सीमा पार होने पर 429 rate_limited मिलता है, साथ में Retry-After। एक और 429 का मतलब इसका लगभग उलटा है — too_many_auth_failures, जहाँ इंतज़ार से कुछ नहीं बनता क्योंकि मना ख़ुद उस पहचान-पत्र को किया जा रहा है। शाखा code पर बनाइए, message पर कभी नहीं।

Webhooks, ताकि लूप पूछता ही न रहे

रिसीवर POST /v1/webhooks से दर्ज कीजिए: url https होना चाहिए, किसी सार्वजनिक होस्ट पर हल होना चाहिए और उसमें कोई पहचान-पत्र नहीं होना चाहिए। हस्ताक्षर का गुप्त कोड बनने के समय एक ही बार वापस आता है, और एक खाते पर ज़्यादा से ज़्यादा पाँच चालू एंडपॉइंट रहते हैं। फ़्लो को जितनों की ज़रूरत है उतनों की ही सदस्यता लीजिए — order.ready, order.completed, order.partially_completed, order.failed, और हर आइटम वाले order.item.sent तथा order.item.expired। हर डिलीवरी के साथ X-NRG-Timestamp, X-NRG-Event-Id और X-NRG-Signature आते हैं; आख़िरी वाला टाइमस्टैम्प, एक बिंदु और कच्ची बॉडी पर HMAC-SHA256 है: जाँच उन्हीं बाइट पर कीजिए जो आपको मिले, दोबारा एन्कोड किए गए JSON पर नहीं, और दोहराव event_id पर हटाइए। POST /v1/webhooks/{webhook_id}/test असली हस्ताक्षरित डिलीवरी उसी रास्ते से भेजता है और बताता है कि आपके एंडपॉइंट ने क्या जवाब दिया — बिना किसी ख़र्च के।

Mode B: हस्ताक्षर आपका, प्रसारण हमारा

b मोड में from और to की जगह signed_tx आता है, यानी हस्ताक्षरित लेन-देन hex में, और ऊर्जा पहुँचते ही हम उसे प्रसारित कर देते हैं — चार मिनट की अवधि पर किसी को बैठकर नज़र नहीं रखनी पड़ती। जो स्वीकार होता है वह जान-बूझकर सँकरा है: USDT अनुबंध का एक transfer कॉल और कुछ नहीं, मालिक का एक ही हस्ताक्षर, साथ में TRX नहीं, और मल्टीसिग मना — क्योंकि किसी अनुमति की कुंजियाँ चेन पर रहती हैं और हमें ख़बर हुए बिना बदल सकती हैं। ऑर्डर बनते समय लेन-देन की उम्र में कम से कम तीन मिनट बचे होने चाहिए, और उसकी अपनी समय-सीमा अवधि को छोटा कर देती है: send_before उस सीमा में से प्रसारण का हाशिया घटाने पर जो बचता है, उससे आगे कभी नहीं जाता। समय पर न भेज पाए तो वह हिस्सा failed होकर बंद होता है, broadcast_window_missed के साथ, और रोकी गई पूरी राशि लौट आती है।

Mode C: बिना किसी प्राप्तकर्ता के नाम के ऊर्जा

c मोड from और kind लेता है, प्राप्तकर्ता बिलकुल नहीं — उस वॉलेट के लिए जिसे आप बैच बनने से पहले ही तैयार रखना चाहते हैं। kind या तो single है या double, और उसे ठीक रखना आपका काम है: प्राप्तकर्ता न होने से मात्रा पढ़ने को कुछ बचता ही नहीं, इसलिए single वहाँ रख देना जहाँ double चाहिए था, ट्रांसफ़र को अधूरा छोड़ देता है और अंतर TRX जला देता है। custom यहाँ जान-बूझकर नहीं दिया जाता, क्योंकि वह किसी ख़ास अनुबंध-प्राप्तकर्ता पर किए गए ड्राई-रन का नतीजा होता है। आइटम to: null लेकर चलते हैं, sent तक कभी नहीं पहुँचते, और अवधि बंद होते ही expired हो जाते हैं: पट्टा ख़त्म हो गया, जो नाकामी नहीं बल्कि सामान्य अंत है — और उसका शुल्क लगता है, क्योंकि ऊर्जा पहुँचा दी गई थी।

अनुरोध में जो कभी नहीं होता

अनुबंध में कहीं भी, किसी भी मोड में, निजी कुंजी के लिए कोई फ़ील्ड नहीं है। mode A आपका लेन-देन कभी देखता ही नहीं। mode B वही देखता है जिस पर आप पहले हस्ताक्षर कर चुके हैं, और उसका एक बाइट भी उस हस्ताक्षर को तोड़े बिना हम बदल नहीं सकते; वह एन्क्रिप्टेड रखा जाता है और ऑर्डर के अंतिम होने के सात दिन बाद मिटा दिया जाता है। mode C के पास देखने को लेन-देन है ही नहीं। API को जो दिया जाता है वे पते हैं (बाक़ी क्या हमारे पास रहता है और क्या नहीं)।

वे हिस्से जिनके लिए कोई कुंजी नहीं चाहिए

संदर्भ एंडपॉइंट और अनुबंध के लिए कोई कुंजी नहीं चाहिए, और उन पर सीमा कुंजी के हिसाब से नहीं, IP के हिसाब से लगती है। GET /v1/tariff बताता है कि इस समय ऊर्जा की एक इकाई sun में कितने की है, कौन सा ज़ोन चल रहा है, next_change_at क्या है, और संदर्भ शेड्यूल क्या है — यही क़ीमतों वाला पन्ना हर बार खुलने पर पढ़ता है। GET /v1/market बताता है कि जिन विक्रेताओं पर हमारी नज़र है वे अपने बारे में क्या प्रकाशित करते हैं, हर आँकड़े पर उसे पढ़े जाने का पल दर्ज, और उन्हीं के बीच हमारी अपनी क़ीमत का क्रम — यही बाज़ार वाला पन्ना है। कोई संख्या नहीं, एंडपॉइंट लिखिए: हमारी क़ीमत हर कुछ मिनट पर दोबारा गिनी जाती है।

अनुबंध ख़ुद https://docs.nrg.market/openapi.yaml पर है, और बाइट-दर-बाइट वही दस्तावेज़ https://api.nrg.market/v1/contract.yaml पर भी — यह जानना काम का है, क्योंकि दस्तावेज़ों वाला होस्ट एक ऐसे किनारे के पीछे बैठा है जो कुछ प्रोग्रामी क्लाइंट को हम तक पहुँचने से पहले ही लौटा देता है। वहाँ ETag बॉडी का SHA-256 है, इसलिए कुछ न बदला हो तो If-None-Match पर 304 मिल जाता है। अपना क्लाइंट उसी फ़ाइल से बनाइए: यह पन्ना सारांश है, और बाध्य हम उसी फ़ाइल से हैं।