Activator — ایڈریس ایکٹیویشن

ایک ایسے TRON ایڈریس کو فعال (ایکٹیویٹ) کریں جو آن چین کبھی استعمال نہ ہوا ہو۔ بالکل نئے ایڈریس کا کوئی اکاؤنٹ ریکارڈ نہیں ہوتا، لہٰذا جب تک اسے فعال نہ کیا جائے وہ ڈیلیگیٹڈ Energy یا Bandwidth حاصل نہیں کر سکتا۔ یہ اینڈ پوائنٹ آپ کے لیے اکاؤنٹ بناتا ہے اور ایکٹیویشن ٹرانزیکشن کا ہیش واپس کرتا ہے۔

ایکٹیویشن فی ایڈریس ایک بار کا عمل ہے۔ اگر ایڈریس پہلے سے فعال ہے تو اینڈ پوائنٹ آپ کو اس کی اطلاع دیتا ہے اور کوئی فیس نہیں لیتا۔

اینڈ پوائنٹ بنیادی URL

https://netts.io/apiv2/activator

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

Header	Required	Description
Content-Type	ہاں	application/json
X-API-KEY	ہاں	Netts ڈیش بورڈ سے آپ کی API کی (key)
X-Real-IP	ہاں	آپ کی وائٹ لسٹ سے IP ایڈریس

آپ کا user_id، API کی سے اخذ کیا جاتا ہے — آپ کو اسے کبھی پاس نہیں کرنا پڑتا۔

---

فعال کریں — POST /apiv2/activator

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

{ "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" }

Field	Type	Required	Description
targetAddress	string	ہاں	فعال کرنے کے لیے TRON ایڈریس۔ لازمی طور پر ^T[A-Za-z0-9]{33}$ سے مماثل ہونا چاہیے (34 حروف، T سے شروع ہوتا ہے)۔

Response — فعال ہو گیا (200، کوڈ 10000)

{
    "detail": {
        "code": 10000,
        "msg": "Address activated successfully, 1.1 TRX deducted",
        "data": {
            "orderId": "A123456",
            "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "activation_cost": 1.1,
            "user_balance_before": 500.00,
            "user_balance_after": 498.90,
            "hash": "0000000000000000000000000000000000000000000000000000000000000000"
        }
    }
}

Field	Type	Description
orderId	string	ایکٹیویشن آرڈر نمبر، ہمیشہ A + ہندسے۔ مفاہمت (reconciliation) کے لیے اسے استعمال کریں۔
targetAddress	string	وہ ایڈریس جو فعال کیا گیا تھا
activation_cost	float	آپ کے بیلنس سے کاٹی گئی رقم، TRX میں
user_balance_before	float	کٹوتی سے پہلے کا بیلنس
user_balance_after	float	کٹوتی کے بعد کا بیلنس
hash	string	ایکٹیویشن ٹرانزیکشن ہیش۔ کسی بھی TRON ایکسپلورر پر اس کی تصدیق کریں۔

Response — پہلے سے فعال ہے (200، کوڈ 2001)

اس وقت واپس آتا ہے جب ایڈریس پہلے سے آن چین موجود ہو۔ کوئی فیس نہیں لی جاتی۔

{
    "detail": {
        "code": 2001,
        "msg": "Address is already activated",
        "data": {
            "targetAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "status": "already_activated",
            "user_balance": 500.00,
            "activation_cost": 0,
            "activation_required": false
        }
    }
}

کٹوتی کا قیاس کرنے سے پہلے code چیک کریں: 10000 کا مطلب ہے کہ آپ نے ادائیگی کی ہے، 2001 کا مطلب ہے کہ آپ نے ادائیگی نہیں کی۔

مثالیں

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

---

قیمت

آئٹم	رقم
ایکٹیویشن	1.1 TRX
ایڈریس پہلے سے فعال ہے	0

رقم مقررہ ہے اور اس کا دارومدار ایڈریس یا نیٹ ورک کے حالات پر نہیں ہوتا۔ یہ ایکٹیویشن کامیاب ہونے کی صورت میں آپ کے Netts بیلنس سے اسی لمحے کاٹی جاتی ہے — اس سے پہلے کبھی نہیں۔ ناکام ایکٹیویشن کی کوئی قیمت نہیں ہوتی۔

آپ کا بیلنس اس لاگت کو پورا کرنے کے لیے کافی ہونا چاہیے، ورنہ درخواست 403 (1004) کے ساتھ مسترد کر دی جاتی ہے اور کوئی آرڈر نہیں بنتا۔

---

آپ کو اس کی کب ضرورت ہوتی ہے

• ایک نئے ایڈریس کے لیے Energy یا Bandwidth کرائے پر لینے سے پہلے۔ غیر موجود اکاؤنٹ کو ڈیلیگیشن ناکام ہو جاتی ہے۔ پہلے فعال کریں، پھر آرڈر کریں۔
• خود بنائے گئے ایڈریس پر پہلی آنے والی ٹرانسفر سے پہلے۔

آپ کو کسی ایسے ایڈریس کے لیے اس اینڈ پوائنٹ کو کال کرنے کی ضرورت نہیں ہے جس پر کبھی TRX یا کوئی ٹوکن موصول ہوا ہو — وہ پہلے سے ہی فعال ہے، اور کال صرف 2001 واپس کرے گی۔

نئے ایڈریس کے لیے Energy کا آرڈر دینا

1 گھنٹے والا Energy اینڈ پوائنٹ آرڈر کے حصے کے طور پر غیر فعال وصول کنندہ کو خود فعال کر دیتا ہے، اور ایکٹیویشن کی لاگت اس آرڈر میں شامل کر دی جاتی ہے۔ جب آپ کسی بھی کرائے سے پہلے ایڈریس کو فعال کرنا چاہتے ہیں تو Activator کو واضح طور پر کال کریں — مثال کے طور پر پہلے Bandwidth ٹاپ اپ کرنے کے لیے، جس کے لیے فعال اکاؤنٹ درکار ہوتا ہے۔

---

وقت کا دورانیہ

ایکٹیویشن ایک حقیقی آن چین ٹرانزیکشن ہے۔ براڈکاسٹ ہونے اور ایکٹیویشن ریکارڈ درج ہونے کے بعد اینڈ پوائنٹ رسپانس دیتا ہے، عام طور پر چند سیکنڈ کے اندر۔

ایڈریس صرف اس وقت قابل استعمال ہوتا ہے جب ٹرانزیکشن بلاک میں شامل ہو جائے — رسپانس کے بعد تقریباً 3 سیکنڈ تک، کیونکہ یہ TRON کا بلاک وقفہ ہے۔ اگر آپ کا اگلا مرحلہ ایڈریس کے فعال ہونے پر منحصر ہے (مثال کے طور پر Bandwidth کا آرڈر دینا)، تو فوری کال کرنے کے بجائے موصول ہونے والے hash کے ذریعے آن چین حالت کی تصدیق کریں۔

---

خرابی کے کوڈ کا حوالہ

Code	Description	HTTP Status
10000	ایڈریس فعال ہو گیا، بیلنس کاٹ لیا گیا	200
2001	ایڈریس پہلے سے فعال ہے، کوئی فیس نہیں لی گئی	200
-1	غلط API کی / IP وائٹ لسٹ میں نہیں ہے	401
1004	ناکافی فنڈز — پیغام میں بیان کیا جاتا ہے کہ کیا درکار ہے اور آپ کے پاس کتنا ہے	403
-	غلط targetAddress فارمیٹ (34 حروف پر مشتمل ہونا چاہیے، T سے شروع ہو)	422
5003	ایکٹیویشن ناکام ہو گئی یا سروس عارضی طور پر دستیاب نہیں ہے — بعد میں دوبارہ کوشش کریں	503
5000	اندرونی سرور کی خرابی	500

503 کا مطلب ہے کہ کوئی کٹوتی نہیں ہوئی اور کوئی ایڈریس فعال نہیں ہوا: درخواست کو محفوظ طریقے سے دوبارہ آزمایا جا سکتا ہے۔

شرح کی حدود

فی ماخذ (source) IP محدود:

دورانیہ	حد
1 سیکنڈ	5 درخواستیں
1 منٹ	60 درخواستیں

Rate Limit Exceeded (429)

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

پوسٹ پیڈ اکاؤنٹس

پوسٹ پیڈ بلنگ والے اکاؤنٹس وہی اینڈ پوائنٹ، ہیڈرز اور Request Body استعمال کرتے ہیں۔ فرق صرف یہ ہے کہ ایکٹیویشن کی ادائیگی کیسے کی جاتی ہے:

• آپ کے ڈپازٹ سے کچھ نہیں کاٹا جاتا۔ ہر کامیاب ایکٹیویشن آپ کے اکاؤنٹ بیلنس میں واجب الادا رقم کے طور پر آپ کے معاہدے میں طے شدہ تصفیہ کی کرنسی میں شامل کی جاتی ہے۔ آپ اپنے معاہدے کے مطابق انوائس کے ذریعے اس کی ادائیگی کرتے ہیں۔
• آپ کے اکاؤنٹ کی ایک کریڈٹ کی حد ہوتی ہے۔ جب تک واجب الادا رقم حد کے اندر ہے، زیرو ڈپازٹ کے ساتھ بھی ایکٹیویشنز قبول کی جاتی ہیں۔
• صرف مکمل شدہ ایکٹیویشن کا بل دیا جاتا ہے۔ وہ ایڈریس جو پہلے سے فعال ہے (2001) اور ناکام ایکٹیویشن پر کوئی چارج نہیں ہوتا۔

درخواست پر نیٹ س (Netts) کی جانب سے اکاؤنٹ کے لیے پوسٹ پیڈ بلنگ فعال کی جاتی ہے۔ ہر رسپانس آپ کو بتاتا ہے کہ ایکٹیویشن کی ادائیگی کیسے کی گئی ہے: paymentMode یا تو postpaid ہوتا ہے یا prepaid۔

اضافی درخواست کے فیلڈز

Field	Type	Required	Description
test	boolean	نہیں	true — صرف قیمت کا حساب لگائیں اور ایڈریس چیک کریں۔ کچھ بھی فعال یا بل نہیں کیا جاتا
freezePrice	boolean	نہیں	true — اپنے معاہدے کے تحت قیمت کو 60 سیکنڈ کے لیے فکس کریں۔ کچھ بھی فعال یا بل نہیں کیا جاتا
quoteId	string	نہیں	اسی ایڈریس کے لیے freezePrice کے ذریعے جاری کردہ کوٹ کی قیمت پر فعال کریں
priceCurrency	string	نہیں	TRX (ڈیفالٹ) یا آپ کے معاہدے کی کرنسی، جیسا کہ settlement.asset میں ہے۔ پوسٹ پیڈ اکاؤنٹس کے لیے آپ کے معاہدے کی کرنسی میں رقوم ہمیشہ شامل ہوتی ہیں

quoteId کو test یا freezePrice کے ساتھ یکجا نہیں کیا جا سکتا۔ Request Body میں موجود کسی بھی دوسرے فیلڈ کو مسترد کر دیا جاتا ہے۔

قیمت کی جانچ (test: true)

{ "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH", "test": true }

{
    "detail": {
        "code": 10010,
        "msg": "Test calculation",
        "data": {
            "amount": 1,
            "unitPriceSun": null,
            "discount": null,
            "energyTRX": "0.000000",
            "activationTRX": "1.100000",
            "wouldCostTRX": "1.100000",
            "paidTRX": 0,
            "paymentMode": "postpaid",
            "activationCheck": "inactive",
            "alt": {"USDC": {"energy": "0.000000", "activation": "0.364333", "total": "0.364333"}},
            "fxAt": "2026-10-19T07:17:33.475335+00:00",
            "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH"
        }
    }
}

activationCheck: inactive — ایڈریس کو فعال کرنے کی ضرورت ہے اور بل وصول کیا جائے گا؛ active — ایڈریس پہلے سے فعال ہے، wouldCostTRX کی قیمت 0 ہے؛ unknown — فی الحال جانچ نہیں کی جا سکی۔

alt.<currency> — آپ کے معاہدے کی کرنسی میں وہی رقوم۔ fxAt — استعمال شدہ شرح مبادلہ کا وقت۔

فکسڈ قیمت کا کوٹ (freezePrice: true)

1. "freezePrice": true کے ساتھ درخواست بھیجیں۔ رسپانس میں کوڈ 10011 (Quote issued)، قیمت کی جانچ والے وہی فیلڈز، نیز quoteId اور expiresAt شامل ہوتے ہیں۔
2. 60 سیکنڈ کے اندر "quoteId": "<quoteId>" اور اسی targetAddress کے ساتھ درخواست بھیجیں۔
3. ایکٹیویشن کا بل کوٹ کی گئی قیمت پر لیا جاتا ہے — کوٹ کے وقت آپ کے معاہدے کے تحت طے شدہ قیمت۔

ایک کوٹ کو ایک بار استعمال کیا جا سکتا ہے۔ میعاد ختم ہونے والے یا پہلے سے استعمال شدہ کوٹ کو مسترد کر دیا جاتا ہے اور کچھ بھی فعال نہیں کیا جاتا۔

کامیاب ایکٹیویشن

{
    "detail": {
        "code": 10000,
        "msg": "Address activated successfully, 1.1 TRX service cost, postpaid",
        "data": {
            "orderId": "A564125",
            "targetAddress": "TSMARToKjQGxroMnPKK6o6d4876VkQmHEH",
            "activation_cost": 1.1,
            "user_balance_before": 0.0,
            "user_balance_after": 0.0,
            "hash": "bd9ea6ef92ce4ba6553af3930a03abe874cdfcc2399b7fdd9abdb11570de2920",
            "paymentMode": "postpaid",
            "activationTRX": "1.100000",
            "totalTRX": "1.100000"
        }
    }
}

Field	Description
activation_cost	TRX میں ایکٹیویشن کی قیمت۔ پوسٹ پیڈ اکاؤنٹس کے لیے یہ ڈپازٹ سے نہیں کاٹی جاتی
user_balance_before / user_balance_after	آپ کا ڈپازٹ — پوسٹ پیڈ اکاؤنٹس کے لیے غیر تبدیل شدہ
paymentMode	postpaid
activationTRX / totalTRX	درست رقوم، 6 اعشاریہ مقامات
quoteId، alt	اس وقت موجود ہوتے ہیں جب ایکٹیویشن کوٹ کے ساتھ لگائی گئی ہو

کریڈٹ کی حد ختم ہو گئی (402)

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

کچھ بھی فعال نہیں کیا جاتا اور کوئی بل نہیں لیا جاتا۔ آپ کی ادائیگی رجسٹر ہونے یا آپ کی حد بڑھ جانے کے بعد نئی ایکٹیویشنز دوبارہ قبول کی جاتی ہیں۔

پوسٹ پیڈ ایرر کوڈز

Code	HTTP	Description
10010	200	قیمت کی جانچ کا نتیجہ (test)
10011	200	کوٹ جاری کر دیا گیا (freezePrice)
1004	402	پوسٹ پیڈ کریڈٹ کی حد ختم ہو گئی
4100	400	غلط درخواست
4101	400	غیر تعاون یافتہ priceCurrency
4102	400	quoteId کو test یا freezePrice کے ساتھ یکجا کیا گیا ہے
4103	409	کوٹ پہلے ہی استعمال ہو چکا ہے
4104	409	کوٹ کی میعاد ختم ہو گئی
4106	404	کوٹ نہیں ملا
4107	409	درخواست کے پیرامیٹرز کوٹ سے مختلف ہیں
4108	400	غلط quoteId فارمیٹ
4109	422	ذیلی اکاؤنٹس کے لیے دستیاب نہیں ہے
5032	503	قیمت عارضی طور پر دستیاب نہیں ہے
5033	503	شرح مبادلہ عارضی طور پر دستیاب نہیں ہے
5034	503	بلنگ عارضی طور پر دستیاب نہیں ہے — ایکٹیویشن قبول نہیں کی گئی تھی
5036	503	کریڈٹ چیک عارضی طور پر دستیاب نہیں ہے — بعد میں دوبارہ کوشش کریں

اوپر دی گئی تمام 4xx اور 503 رسپانسز کے لیے کچھ بھی فعال نہیں کیا جاتا اور کوئی بل نہیں لیا جاتا۔

---

نوٹس

• Idempotency آپ کی ذمہ داری ہے۔ اینڈ پوائنٹ میں کوئی idempotency کلید نہیں ہے۔ ایسے ایڈریس کے لیے درخواست دہرانا جو پہلے سے فعال ہو، محفوظ اور مفت ہے (2001)، لیکن ایک ہی بالکل نئے ایڈریس کے لیے بیک وقت دو درخواستیں آگے بڑھ سکتی ہیں۔ اپنی طرف سے فی ایڈریس ایکٹیویشن کو ترتیب وار بنائیں۔
• orderId کا فارمیٹ A + ہندسے ہے اور یہ تمام ایکٹیویشنز میں منفرد ہوتا ہے۔
• آج ایکٹیویشن کے لیے کوئی ویب ہک نہیں بھیجا جاتا — رسپانس اور hash ہی تصدیق ہیں۔ ویب ہکس فی الحال صرف تصدیق شدہ Energy ڈیلیگیشنز کا احاطہ کرتے ہیں، دیکھیں Webhooks۔