POST /apiv2/order5m

Netts کے اندرونی Energy پولز کے ذریعے 5 منٹ کا Energy کرایہ آرڈر بنائیں۔

اینڈ پوائنٹ URL

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

درخواست کے ہیڈرز

ہیڈر	لازمی	تفصیل
Content-Type	ہاں	application/json
X-API-KEY	ہاں	آپ کی API کی Netts ڈیش بورڈ سے
X-Real-IP	ہاں	آپ کی وائٹ لسٹ سے IP پتہ

درخواست کا باڈی

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

پیرامیٹرز

پیرامیٹر	قسم	لازمی	تفصیل
amount	integer	ہاں	کرایہ پر لینے کے لیے Energy کی مقدار (کم از کم: 61,000، زیادہ سے زیادہ: 650,000)
receiveAddress	string	ہاں	TRON پتہ جو Energy وصول کرے گا (TRC-20 فارمیٹ)

Energy کی حدود

5 منٹ کا اینڈ پوائنٹ فی آرڈر 61,000 اور 650,000 یونٹس کے درمیان Energy کی مقدار قبول کرتا ہے۔ اس حد سے باہر کی درخواستیں HTTP 400 کے ساتھ مسترد کر دی جائیں گی۔

فراہم کنندہ کی معلومات

5 منٹ کے Energy آرڈرز خصوصی طور پر Netts اندرونی Energy پولز کے ذریعے مکمل کیے جاتے ہیں۔ 1 گھنٹے کے اینڈ پوائنٹ کے برعکس، بیرونی فراہم کنندگان استعمال نہیں کیے جاتے۔

دستیابی اور دوبارہ کوشش کی حکمت عملی

چونکہ ڈیلیگیشنز صرف اندرونی پولز سے آتی ہیں، اس لیے زیادہ مانگ کے اوقات میں عارضی عدم دستیابی ممکن ہے۔ اگر آپ کو 503 ایرر موصول ہوتا ہے، تو تھوڑی تاخیر کے بعد درخواست کی دوبارہ کوشش کریں یا 1 گھنٹے کے اینڈ پوائنٹ پر رجوع کریں جس کے پاس متعدد بیرونی فراہم کنندگان تک رسائی ہے۔

امثلہ برائے درخواستیں

cURL

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

Python

import requests

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

payload = {
    "amount": 65000,
    "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')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
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, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

پتہ کی ایکٹیویشن کے ساتھ کامیابی (200 OK)

جب وصول کنندہ کا پتہ TRON نیٹ ورک پر ایکٹیویٹ نہ ہو، تو Netts اسے خودکار طور پر ایکٹیویٹ کر دیتا ہے۔ ایکٹیویشن لاگت کل رقم میں شامل کر دی جاتی ہے:

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc..."
        }
    }
}

جواب کے فیلڈز

فیلڈ	قسم	تفصیل
detail.code	integer	کامیاب آرڈرز کے لیے ہمیشہ 10000
detail.msg	string	کٹوتی شدہ رقم کے ساتھ کامیابی کا پیغام
detail.data.orderId	string	یکساں آرڈر ID (فارمیٹ: 5M{id})
detail.data.paidTRX	number	TRX میں کل لاگت (اگر لاگو ہو تو ایکٹیویشن فیس شامل ہے)
detail.data.hash	string	ڈیلیگیشن ٹرانزیکشن ہیش
detail.data.delegateAddress	string	پول کا پتہ جس نے Energy ڈیلیگیٹ کی
detail.data.energy	integer	Energy کی مقدار + بفر (عام طور پر +50)
detail.data.activationHash	string	صرف تب موجود ہوتا ہے اگر پتہ کی ایکٹیویشن کی گئی ہو

خرابی کے جوابات

غلط Energy کی مقدار (400)

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

تصدیقی خرابی (401)

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

ناکافی بیلنس (403)

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

سروس دستیاب نہیں ہے (503)

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

503 ایررز سے نمٹنا

503 جواب کا مطلب ہے کہ اندرونی پولز عارضی طور پر مکمل گنجائش پر ہیں۔ تجویز کردہ حکمت عملی:

1. 2-3 سیکنڈ انتظار کریں اور 5 منٹ کے آرڈر کی دوبارہ کوشش کریں
2. اگر پھر بھی دستیاب نہ ہو، تو 1 گھنٹے کے اینڈ پوائنٹ پر رجوع کریں جو متعدد فراہم کنندگان استعمال کرتا ہے

اندرونی سرور کی خرابی (500)

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

ایرر کوڈ حوالہ جات

کوڈ	تفصیل	HTTP اسٹیٹس
10000	کامیابی	200
10000	کامیابی (کیشڈ جواب)	208
-	ڈپلیکیٹ درخواست پر ابھی کارروائی ہو رہی ہے	409
1003	Energy کی مقدار حد سے باہر ہے	400
1004	ناکافی بیلنس	403
1005	صارف کا ادائیگی کنندہ پتہ تشکیل شدہ نہیں ہے	400
5000	اندرونی سرور کی خرابی	500
5003	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 آئیڈیمپوٹینسی کی حمایت کرتی ہے۔ جب آپ متعدد ایک جیسی درخواستیں بھیجتے ہیں، تو نظام اس بات کو یقینی بناتا ہے کہ آرڈر پر صرف ایک بار کارروائی ہو۔

آئیڈیمپوٹینسی کیسے کام کرتی ہے

درخواست کی انفرادیت کا تعین مندرجہ ذیل کے امتزاج سے ہوتا ہے:

• درخواست کا ٹائم اسٹیمپ (2 سیکنڈ کی ونڈو)
• Energy کی مقدار
• وصول کنندہ کا پتہ
• API کی

ہر درخواست کو 2 سیکنڈ کی انفرادیت کی ونڈو دی جاتی ہے۔ اس ونڈو کے اندر یکساں پیرامیٹرز والی درخواستوں کو ڈپلیکیٹ سمجھا جاتا ہے۔

ڈپلیکیٹ درخواستوں کے لیے HTTP اسٹیٹس کوڈز

اسٹیٹس کوڈ	نام	تفصیل
200	OK	آرڈر کامیابی کے ساتھ پروسیس ہو گیا (پہلی درخواست)
208	Already Reported	آرڈر پہلے ہی پروسیس ہو چکا تھا، کیشڈ جواب واپس آ رہا ہے
409	Conflict	درخواست پر فی الحال کارروائی ہو رہی ہے، دوبارہ کوشش نہ کریں

ڈپلیکیٹ درخواست - پہلے ہی پروسیس شدہ (208)

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

ڈپلیکیٹ درخواست - ابھی کارروائی ہو رہی ہے (409)

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

بہترین طریقہ کار

• ایک جیسے پیرامیٹرز کے ساتھ متوازی درخواستیں نہ بھیجیں - ہر جواب کا انتظار کریں
• فوراً دوبارہ کوشش کرنے کے بجائے انتظار کر کے 409 جوابات سے نمٹیں
• کیشڈ جوابات کی شناخت کے لیے idempotency.cached فیلڈ کو چیک کریں

موازنہ: 5 منٹ بمقابلہ 1 گھنٹے کے آرڈرز

خصوصیت	5 منٹ کا آرڈر	1 گھنٹے کا آرڈر
اینڈ پوائنٹ	/apiv2/order5m	/apiv2/order1h
دورانیہ	5 منٹ	1 گھنٹہ
Energy کی حد	61,000 - 650,000	61,000 - 3,000,000
فراہم کنندگان	صرف Netts اندرونی پولز	اندرونی پولز + بیرونی فراہم کنندگان
قیمت	کم (5 منٹ کی شرح)	معیاری فی گھنٹہ شرح
دستیابی	رش کے اوقات میں محدود ہو سکتی ہے	زیادہ (متعدد فراہم کنندگان کے متبادل)
بہترین برائے	بار بار ہونے والی چھوٹی ٹرانزیکشنز	بڑی یا یقینی ترسیل

نوٹس

• کامیاب آرڈر پر Energy فوری طور پر فراہم کر دی جاتی ہے (عام طور پر 0.5-2 سیکنڈ کے اندر)
• API جواب کا ٹائم آؤٹ: زیادہ سے زیادہ 10 سیکنڈ (اس میں اندرونی دوبارہ کوششیں شامل ہیں)
• پتہ کی ایکٹیویشن: اگر وصول کنندہ کا پتہ ایکٹیویٹ نہیں ہے، تو Netts اسے اصل لاگت کی قیمت پر ایکٹیویٹ کرتا ہے۔ ایکٹیویشن لاگت فی پتہ صرف ایک بار وصول کی جاتی ہے
• دورانیہ: مقررہ 5 منٹ (300 سیکنڈ)
• Energy کی کم از کم مقدار: 61,000 یونٹس
• Energy کی زیادہ سے زیادہ مقدار: 650,000 یونٹس فی آرڈر
• Energy بفر: +50 یونٹس خودکار طور پر شامل کیے جاتے ہیں (مفت)
• آرڈر ID فارمیٹ: یکساں ٹریکنگ کے لیے 5M{id}
• قیمتوں کا تعین: Pricing API کے ذریعے دن کے وقت کی بنیاد پر متحرک
• شرح کی حد بندی: فی IP پتہ 50 درخواستیں فی سیکنڈ
• صرف اندرونی پولز: اگر پولز مکمل گنجائش پر ہوں، تو تھوڑی تاخیر کے بعد دوبارہ کوشش کریں یا متبادل کے طور پر 1 گھنٹے کے اینڈ پوائنٹ کا استعمال کریں