POST /apiv2/order1h

स्वचालित फ़ेलओवर के साथ एकाधिक Energy प्रदाताओं के माध्यम से 1 घंटे का Energy रेंटल ऑर्डर बनाएं।

एंडपॉइंट URL

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

अनुरोध हेडर

हेडर	आवश्यक	विवरण
Content-Type	हाँ	application/json
X-API-KEY	हाँ	Netts डैशबोर्ड से आपकी API कुंजी
X-Real-IP	हाँ	आपकी श्वेतसूची (whitelist) से IP पता

अनुरोध बॉडी

{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

पैरामीटर

पैरामीटर	प्रकार	आवश्यक	विवरण
amount	integer	हाँ	किराए पर ली जाने वाली Energy की मात्रा (न्यूनतम: 61000, अधिकतम: 3000000)
receiveAddress	string	हाँ	TRON पता जो Energy प्राप्त करेगा (TRC-20 प्रारूप)

प्रदाता चयन

API स्वचालित रूप से निम्नलिखित के आधार पर इष्टतम Energy प्रदाता का चयन करता है:

• लागत दक्षता - हमेशा सबसे कम उपलब्ध मूल्य ढूँढता है
• उपलब्धता - पर्याप्त Energy भंडार सुनिश्चित करता है
• विश्वसनीयता - उच्च सफलता दर वाले प्रदाताओं का उपयोग करता है
• गति - सबसे तेज़ डिलीवरी समय को प्राथमिकता देता है

उदाहरण अनुरोध

cURL

curl -X POST https://netts.io/apiv2/order1h \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 131000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

import requests

url = "https://netts.io/apiv2/order1h"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 131000,
    "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')}")
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)}")

प्रतिक्रिया

सफल प्रतिक्रिया (200 OK)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.23 TRX deducted",
        "data": {
            "orderId": "1H123456",
            "paidTRX": 2.23,
            "hash": "a1b2c3d4e5f6789...",
            "delegateAddress": "TDelegatePoolAddress...",
            "energy": 131050
        }
    }
}

प्रतिक्रिया फ़ील्ड

फ़ील्ड	प्रकार	विवरण
detail.code	integer	सफल ऑर्डर के लिए हमेशा 10000
detail.msg	string	कटी हुई राशि के साथ सफलता संदेश
detail.data.orderId	string	एकीकृत ऑर्डर ID (प्रारूप: 1H{request_id})
detail.data.paidTRX	number	TRX में कुल लागत (यदि पता सक्रिय नहीं था तो सक्रियण शुल्क शामिल है)
detail.data.hash	string | null	ट्रांजेक्शन हैश। फ़ील्ड हमेशा मौजूद रहता है लेकिन खाली हो सकता है - कुछ प्रदाता तुरंत हैश नहीं लौटाते हैं। हैश प्राप्त करने के लिए 1 मिनट बाद /apiv2/order_check का उपयोग करें
detail.data.delegateAddress	string	पूल का पता जिसने Energy डेलिगेट की
detail.data.energy	integer	Energy की मात्रा + बफर (आमतौर पर +50)

त्रुटि प्रतिक्रियाएं

प्रमाणीकरण त्रुटि (401)

{
    "detail": "Invalid API key or IP not in whitelist"
}

अपर्याप्त शेष राशि (403)

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 2.23 TRX, Available: 1.50 TRX"
}

सेवा अनुपलब्ध (503)

{
    "code": 5003,
    "msg": "Service temporarily unavailable. All energy providers are currently unavailable."
}

प्रदाता त्रुटियां (503)

{
    "code": 5001,
    "msg": "Energy provider temporarily unavailable"
}

{
    "code": 5002,
    "msg": "Energy provider temporarily unavailable"
}

{
    "code": 5004,
    "msg": "Energy provider requires higher minimum amount"
}

आंतरिक सर्वर त्रुटि (500)

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

त्रुटि कोड संदर्भ

कोड	विवरण	HTTP स्थिति
10000	सफलता	200
10000	सफलता (कैश की गई प्रतिक्रिया)	208
-	डुप्लिकेट अनुरोध अभी भी संसाधित हो रहा है	409
1004	अपर्याप्त शेष राशि	403
5000	आंतरिक सर्वर त्रुटि	500
5001	Energy प्रदाता अनुपलब्ध है	503
5002	Energy प्रदाता अनुपलब्ध है	503
5003	Energy सेवा अनुपलब्ध है	503
5004	Energy प्रदाता की न्यूनतम सीमा पूरी नहीं हुई	503

दर सीमाएं

इस एंडपॉइंट पर निम्नलिखित दर सीमाएं लागू होती हैं (प्रति IP पता):

अवधि	सीमा	विवरण
1 सेकंड	50 अनुरोध	अधिकतम 50 अनुरोध प्रति सेकंड

दर सीमा हेडर

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

दर सीमा पार हो गई (429)

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

Idempotency

API डुप्लिकेट ऑर्डर प्रोसेसिंग को रोकने के लिए idempotency का समर्थन करता है। जब आप एकाधिक समान अनुरोध भेजते हैं, तो सिस्टम यह सुनिश्चित करता है कि ऑर्डर केवल एक बार ही संसाधित हो।

Idempotency कैसे काम करता है

अनुरोध की विशिष्टता निम्नलिखित के संयोजन द्वारा निर्धारित की जाती है:

• अनुरोध टाइमस्टैम्प (1-सेकंड की विंडो)
• Energy की मात्रा
• प्राप्तकर्ता का पता
• API कुंजी

प्रत्येक अनुरोध को 1-सेकंड की विशिष्टता विंडो दी जाती है। सिस्टम को दुरुपयोग से बचाने और उचित प्रोसेसिंग सुनिश्चित करने के लिए, समान मापदंडों वाले अनुरोध प्रति सेकंड एक से अधिक बार नहीं भेजे जा सकते।

वर्तमान व्यवहार: सिस्टम पहले से ऑर्डर की गई Energy पर गलत पुनः प्रयासों (retries) से क्लाइंट्स की स्वचालित रूप से सुरक्षा करता है। यदि आप गलती से एक ही अनुरोध दो बार भेजते हैं, तो आपसे दो बार शुल्क नहीं लिया जाएगा।

अपनी स्वयं की कुंजी प्रदान करना

आप X-Idempotency-Key हेडर भेजकर idempotency को अपने नियंत्रण में ले सकते हैं। जब यह मौजूद होता है, तो केवल वही मान तय करता है कि अनुरोध दोहराया गया है या नहीं, और ऊपर दिए गए स्वचालित संयोजन का उपयोग नहीं किया जाता है। जब यह अनुपस्थित होता है, तो कुछ भी नहीं बदलता है — सर्वर आपके लिए कुंजी प्राप्त करता है।

हेडर	X-Idempotency-Key
प्रारूप	बिल्कुल 64 लोअरकेस हेक्साडेसिमल वर्ण — एक SHA-256 डाइजेस्ट
जीवनकाल	उस कुंजी वाले पहले अनुरोध से 24 घंटे
दायरा	आपका खाता। किसी भिन्न खाते द्वारा भेजा गया समान मान कभी भी आपका परिणाम नहीं लौटाता है

किसी भी अन्य प्रारूप की कुंजी — डैश के साथ UUID, base64, अपरकेस हेक्स — ऑर्डर दिए जाने से पहले और कोई भी शुल्क काटे जाने से पहले 400 के साथ अस्वीकार कर दी जाती है:

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

यह प्रारूप अन्य एंडपॉइंट्स से भिन्न है। /apiv2/withdraw, /apiv2/bandwidth और ऑर्केस्ट्रेटर 16–64 वर्णों की base64 कुंजी स्वीकार करते हैं। यह एंडपॉइंट केवल 64-वर्णों का हेक्स डाइजेस्ट स्वीकार करता है, इसलिए उन एंडपॉइंट्स से कॉपी किया गया कुंजी-निर्माण कोड यहाँ 400 लौटाता है।

कुंजी कैसे बनाएं

इसे अपनी API कुंजी से प्राप्त करें। यह मान को आपके खाते के लिए अद्वितीय बनाता है, पुनः प्रयास पर प्रतिलिपि प्रस्तुत करने योग्य बनाता है, और किसी अन्य के लिए इस तक पहुँचना असंभव बनाता है:

import hashlib
import hmac

def make_idempotency_key(api_key: str, address: str, amount: int, nonce: str) -> str:
    message = f"{address}:{amount}:{nonce}"
    return hmac.new(api_key.encode(), message.encode(), hashlib.sha256).hexdigest()

nonce ऑर्डर से संबंधित है, अनुरोध से नहीं। इसे एक बार चुनें, जब आपकी ओर से ऑर्डर बनाया जाता है, और उस ऑर्डर के प्रत्येक भेजने पर वही मान पास करें — पहला प्रयास और प्रत्येक पुनः प्रयास समान रूप से। भेजने वाले फ़ंक्शन के अंदर एक नया मान उत्पन्न करना (प्रत्येक कॉल पर str(uuid.uuid4())) प्रत्येक प्रयास को एक अलग कुंजी देता है, इसलिए टाइमआउट के बाद का पुनः प्रयास दूसरे ऑर्डर के रूप में स्वीकार कर लिया जाता है और फिर से शुल्क लिया जाता है। सबसे सरल सही विकल्प वह ऑर्डर आईडी है जो आपके पास पहले से है: यह पहले प्रयास से पहले मौजूद होती है और आपकी प्रक्रिया के पुनरारंभ होने के बाद भी बनी रहती है।

# एक बार, जब ऑर्डर आपके सिस्टम में दिखाई देता है
order = create_order(address="TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE", amount=131000)

# पहले प्रयास पर और प्रत्येक पुनः प्रयास पर — वही तीन इनपुट, वही कुंजी
key = make_idempotency_key(API_KEY, order.address, order.amount, order.id)

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Idempotency-Key": key,
}

एक कुंजी 24 घंटे तक जीवित रहती है। उसके बाद वही nonce फिर से खाली हो जाता है और एक नया ऑर्डर शुरू करता है।

ऐसे मान का उपयोग न करें जिस तक कोई अन्य पहुँच सके — 64 शून्य, एक निश्चित शब्द का डाइजेस्ट। कुंजियाँ सभी खातों में एक ही स्थान साझा करती हैं। ऐसा टकराव कभी भी किसी अन्य खाते के ऑर्डर को उजागर नहीं करता है, लेकिन जब तक उनकी कुंजी समाप्त नहीं हो जाती, तब तक आपका अनुरोध 409 के साथ अस्वीकार कर दिया जाता है, जो वह उत्तर नहीं है जो आप पुनः प्रयास के दौरान चाहते हैं।

दो समान ऑर्डर देना

कभी-कभी आप वास्तव में एक ही ऑर्डर दो बार चाहते हैं — एक के बाद एक उसी पते पर उतनी ही मात्रा में Energy। स्वचालित कुंजी इसे पुनः प्रयास से अलग नहीं बता सकती: दोनों अनुरोध बाइट-दर-बाइट समान होते हैं, और केवल उनके आने का समय ही उन्हें अलग करता है।

अपनी स्वयं की कुंजी के बिना, परिणाम उनके बीच के अंतराल पर निर्भर करता है:

दोनों अनुरोधों के बीच का अंतराल	क्या होता है
उसी 1-सेकंड की विंडो के अंदर	दूसरा अनुरोध एक दोहराव माना जाता है। इसे निष्पादित नहीं किया जाता है: आपको 208 और पहले ऑर्डर की प्रतिक्रिया मिलती है, जिसमें orderId शामिल है। इसके लिए कुछ भी शुल्क नहीं लिया जाता है
एक सेकंड से अधिक का अंतर	दो अलग-अलग कुंजियाँ — दोनों ऑर्डर दिए जाते हैं और दोनों का शुल्क लिया जाता है

इसलिए यदि आप स्वचालित कुंजी पर भरोसा करते हैं, तो दो समान ऑर्डरों के बीच एक सेकंड से अधिक का अंतर छोड़ें, और स्थिति कोड पढ़ें: 208 का अर्थ है कि आपके द्वारा अभी भेजा गया ऑर्डर नहीं दिया गया था।

रोकना (pause) एक समाधान (workaround) है, कोई स्थायी समाधान नहीं। यह प्रत्येक अनुरोध को अलग करता है, जिसमें वे भी शामिल हैं जिन्हें आपने कभी दोहराना नहीं चाहा था — टाइमआउट के बाद पुनः प्रयास, एक डबल क्लिक, आपकी कतार द्वारा फिर से डिलीवर किया गया संदेश। वे भी विंडो के बाद आते हैं, इसलिए उन्हें अलग ऑर्डर के रूप में रखा जाता है और अलग से शुल्क लिया जाता है। इस एंडपॉइंट का प्रतिक्रिया टाइमआउट 10 सेकंड है, जो पहले से ही विंडो से काफी बाहर है: स्वचालित कुंजी टाइमआउट के बाद होने वाले पुनः प्रयास की रक्षा नहीं करती है।

आपकी अपनी कुंजी अनुमान लगाने की आवश्यकता को समाप्त कर देती है, क्योंकि निर्णय एकमात्र उस पक्ष के पास चला जाता है जो उत्तर जानता है:

आप क्या कर रहे हैं	आप क्या भेजते हैं	परिणाम
एक दूसरा, वास्तव में नया ऑर्डर	एक नया nonce	एक नई कुंजी — ऑर्डर दिया जाता है
किसी ऐसे ऑर्डर का पुनः प्रयास जिसका परिणाम आपको नहीं पता है	पहले प्रयास का nonce	वही कुंजी — 208, मूल प्रतिक्रिया, कोई दूसरा शुल्क नहीं

दूसरी पंक्ति ही वह कारण है जिसके लिए हेडर मौजूद है, और यहीं पर कार्यान्वयन में आमतौर पर चूक होती है: कुंजी कैसे बनाएं के अंतर्गत नोट देखें।

डुप्लिकेट अनुरोधों के लिए HTTP स्थिति कोड

स्थिति कोड	नाम	विवरण
200	OK	ऑर्डर सफलतापूर्वक संसाधित हुआ (पहला अनुरोध)
208	Already Reported	ऑर्डर पहले ही संसाधित हो चुका था, कैश की गई प्रतिक्रिया लौटाई जा रही है
409	Conflict	अनुरोध वर्तमान में संसाधित किया जा रहा है, पुनः प्रयास न करें

डुप्लिकेट अनुरोध - पहले ही संसाधित हो चुका है (208)

जब पहले से पूर्ण किए गए ऑर्डर के लिए डुप्लिकेट अनुरोध प्राप्त होता है:

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 2.54 TRX deducted",
        "data": {
            "hash": "9e4c20e21e01e4c39b21b670d1ea1fc1e4b0de94d8fbd4c190d5378ba911dfae",
            "energy": 65050,
            "orderId": "1H70bcc7962a",
            "paidTRX": 2.535,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2025-12-03T10:34:49.104896"
    }
}

प्रतिक्रिया निकाय मूल सफल प्रतिक्रिया के समान ही होता है, जिसमें एक अतिरिक्त idempotency ऑब्जेक्ट यह दर्शाता है कि यह एक कैश की गई प्रतिक्रिया है।

डुप्लिकेट अनुरोध - अभी भी संसाधित हो रहा है (409)

जब कोई डुप्लिकेट अनुरोध तब आता है जब मूल अनुरोध अभी भी संसाधित हो रहा हो:

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "idempotency_key": "b9e67b2412d33c92...",
    "retry_after_seconds": 3
}

सिफारिश: ऑर्डर की स्थिति की जाँच करने से पहले निर्दिष्ट retry_after_seconds तक प्रतीक्षा करें।

सर्वोत्तम प्रथाएं

• समान मापदंडों के साथ समानांतर अनुरोध न भेजें - प्रत्येक प्रतिक्रिया की प्रतीक्षा करें
• प्रत्येक नए ऑर्डर के लिए एक नए nonce का उपयोग करें, और इसके प्रत्येक पुनः प्रयास के लिए पहले प्रयास के nonce का उपयोग करें
• भेजने के समय कभी भी nonce का पुनर्निर्माण न करें — पुनः प्रयास में पहले प्रयास की कुंजी ही दोबारा बननी चाहिए, कोई नई कुंजी नहीं
• तुरंत पुनः प्रयास करने के बजाय प्रतीक्षा करके 409 प्रतिक्रियाओं को संभालें
• कैश की गई प्रतिक्रियाओं की पहचान करने के लिए idempotency.cached फ़ील्ड की जाँच करें — 208 का अर्थ है कि आपके द्वारा अभी भेजा गया ऑर्डर नहीं दिया गया था

नोट्स

• सफल ऑर्डर पर Energy तुरंत वितरित की जाती है (आमतौर पर 0.5-10 सेकंड के भीतर)
• API प्रतिक्रिया टाइमआउट: अधिकतम 10 सेकंड, आमतौर पर 2 सेकंड तक प्रतिक्रिया देता है
• पता सक्रियण: यदि प्राप्तकर्ता का पता सक्रिय नहीं है, तो Netts इसे लागत मूल्य पर सक्रिय करता है
• सक्रियण विलंब: गैर-सक्रिय पतों के लिए, सक्रियण प्रक्रिया के कारण API प्रतिक्रिया में 6 सेकंड तक का समय लग सकता है
• स्वचालित प्रदाता फ़ेलओवर के साथ ऑर्डर 24/7 संसाधित किए जाते हैं
• न्यूनतम Energy राशि: 61,000 यूनिट
• अधिकतम Energy राशि: प्रति ऑर्डर 3,000,000 यूनिट
• Energy बफर: प्रदाता क्षतिपूर्ति के लिए +50 यूनिट स्वचालित रूप से जोड़े जाते हैं (निःशुल्क)
• ट्रांजेक्शन हैश: फ़ील्ड हमेशा मौजूद रहता है लेकिन खाली हो सकता है यदि प्रदाता इसे तुरंत वापस नहीं करता है। हैश प्राप्त करने के लिए, ऑर्डर देने के 1 मिनट से पहले /apiv2/order_check पर कॉल न करें
• प्रदाता चयन: लागत और उपलब्धता के आधार पर स्वचालित
• ऑर्डर ID प्रारूप: एकीकृत ट्रैकिंग के लिए 1H{request_id}
• मूल्य निर्धारण: दिन के समय और Energy की मात्रा के आधार पर गतिशील
• अवधि: निश्चित 1 घंटा (3600 सेकंड)
• दर सीमा (Rate limiting): 50 अनुरोध प्रति सेकंड प्रति IP पता