POST /apiv2/time/add

ایک TRON ایڈریس کو Host Mode میں شامل کریں اور، اختیاری طور پر، ڈیلیگیشن کی اطلاعات کے لیے ایک کال بیک URL رجسٹر کریں۔

اینڈپوائنٹ URL

POST https://netts.io/apiv2/time/add

تصدیق (Authentication)

اپنی API کلید درخواست کے باڈی (api_key) میں یا X-API-KEY ہیڈر میں فراہم کریں۔ درخواست کا IP اس وائٹ لسٹ میں ہونا ضروری ہے جو آپ کی API کلید کے لیے ترتیب دی گئی ہے۔

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

json

{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",
    "infinity": true
}

پیرامیٹرز

پیرامیٹر	قسم	لازمی	تفصیل
api_key	string	ہاں*	API کلید۔ اسے `X-API-KEY` ہیڈر میں بھی بھیجا جا سکتا ہے۔
address	string	ہاں	TRON (TRC-20) ایڈریس، لازمی طور پر `^T[1-9A-HJ-NP-Za-km-z]{33}$` سے مطابقت رکھتا ہو (`T` سے شروع ہوتا ہے، 34 حروف)۔
callback_url	string	نہیں	پبلک HTTP/HTTPS URL جس پر ایڈریس کو Energy ڈیلیگیٹ کیے جانے پر مطلع کیا جائے گا۔ زیادہ سے زیادہ 2048 حروف۔
infinity	boolean	نہیں	`true` — ایڈریس کو براہ راست infinity موڈ میں بھی تبدیل کر دیتا ہے، جس سے `/apiv2/time/infinitystart` پر الگ کال کرنے کی بچت ہوتی ہے۔ ڈیفالٹ `false` ہے۔

* باڈی میں لازمی ہے الا یہ کہ X-API-KEY ہیڈر استعمال کیا گیا ہو۔

callback_url کی توثیق: لازمی طور پر http/https ہونا چاہیے، صرف ایک پبلک ہوسٹ (localhost، پرائیویٹ RFC1918 رینجز، لنک-لوکل 169.254.0.0/16، IPv6 پرائیویٹ/لنک-لوکل، مخصوص اور ملٹی کاسٹ ایڈریسز مسترد کر دیے جاتے ہیں)، اور زیادہ سے زیادہ 2048 حروف۔

رویہ (Behaviour)

اگر ایڈریس نیا ہے، تو اسے غیر فعال (inactive) اسٹیٹس (status = 0، cycle_set = 0) کے ساتھ Host Mode میں شامل کیا جاتا ہے۔ اسے بعد میں /apiv2/time/order یا /apiv2/time/infinitystart کے ذریعے فعال کریں۔
اگر ایڈریس پہلے ہی آپ کے اکاؤنٹ کے تحت موجود ہے، تو یہ کال اس کے کال بیک URL کو اپ ڈیٹ کرتی ہے۔
اگر callback_url فراہم کیا گیا ہے، تو اسے اس ایڈریس کے لیے محفوظ (یا اپ ڈیٹ) کر دیا جاتا ہے۔

infinity

"infinity": true کے ساتھ ایڈریس کو ایک ہی کال میں شامل اور infinity موڈ میں فعال کیا جاتا ہے — بالکل وہی نتیجہ جو /apiv2/time/add اور پھر /apiv2/time/infinitystart کو کال کرنے سے ملتا ہے۔ بلنگ الگ کال کے بالکل مماثل ہے: اس مرحلے پر کوئی چارج نہیں لیا جاتا، اور جیسے جیسے Energy ڈیلیگیٹ ہوتی ہے سائیکلز کا ایک ایک کر کے چارج لیا جاتا ہے۔ دیکھیں Host Mode → Cycles and Pricing۔

ایڈریس کو شامل کرنا اور اسے آن کرنا دو الگ الگ مراحل ہیں، اور صرف پہلے مرحلے کی ضمانت دی جاتی ہے۔ رسپانس شامل کرنے کا نتیجہ ظاہر کرتا ہے۔ اگر ایڈریس شامل کر دیا گیا تھا لیکن اسے آن نہیں کیا جا سکا، تب بھی یہ کال حسب معمول پیغام کے ساتھ code: 0 واپس کرتی ہے — ایڈریس کو بس غیر فعال چھوڑ دیا جاتا ہے، بالکل ایسے ہی جیسے آپ نے فلیگ پاس نہ کیا ہو۔ آن کرنے کا عمل چھوڑ دیا جاتا ہے جب:

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

فلیگ کے ساتھ اور فلیگ کے بغیر رسپانس یکساں ہوتا ہے — کوئی اضافی فیلڈز نہیں، کوئی اضافی ایرر کوڈز نہیں، اور یہ آپ کو یہ نہیں بتاتا کہ آیا infinity موڈ درحقیقت آن ہوا تھا یا نہیں۔ اس کی تصدیق Time Status کے ساتھ کریں: ایڈریس status: "active" اور mode: "infinity" رپورٹ کرتا ہے، اور آرڈر کی ID اسی رسپانس میں ہوتی ہے۔ اس اینڈپوائنٹ سے code: 0 کو اس بات کا ثبوت نہ سمجھیں کہ موڈ چل رہا ہے۔

نمونہ درخواستیں

cURL

bash

curl -X POST https://netts.io/apiv2/time/add \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/time/add"
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",  # optional
    # "infinity": True,  # optional: also switch the address into infinity mode
}

resp = requests.post(url, json=data, timeout=30)
result = resp.json()

if result["code"] == 0:
    print("Added:", result["data"]["address"])
else:
    print("Error:", result["msg"])

Node.js

javascript

const axios = require('axios');

const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    // callback_url: 'https://your-server.com/webhook', // optional
    // infinity: true, // optional: also switch the address into infinity mode
};

axios.post('https://netts.io/apiv2/time/add', data)
    .then(({ data: result }) => {
        if (result.code === 0) console.log('Added:', result.data.address);
        else console.error('Error:', result.msg);
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

رسپانس

کامیابی (نیا ایڈریس)

json

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://your-server.com/webhook",
        "timestamp": "2026-07-13T05:30:15.123456"
    }
}

کامیابی (موجودہ ایڈریس کے لیے کال بیک URL اپ ڈیٹ ہو گیا)

json

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2026-07-13T05:35:20.789012"
    }
}

رسپانس فیلڈز

فیلڈ	قسم	تفصیل
code	integer	`0` = کامیابی، منفی = خرابی
msg	string	انسان کے پڑھنے کے قابل پیغام
data.address	string	وہ ایڈریس جو شامل/اپ ڈیٹ کیا گیا تھا
data.callback_url	string \| null	رجسٹرڈ کال بیک URL (اگر کوئی نہ ہو تو `null`)
data.timestamp	string	آپریشن کا ISO ٹائم اسٹیمپ

خرابی کے رسپانسز

تمام خرابیاں code = -1 استعمال کرتی ہیں اور msg میں مسئلہ بیان کرتی ہیں:

msg	وجہ
`API key required in X-API-KEY header or request body`	کوئی API کلید فراہم نہیں کی گئی
`Invalid API key or IP not in whitelist`	تصدیق ناکام ہو گئی
`Invalid TRC-20 address format`	ایڈریس مطلوبہ فارمیٹ سے مطابقت نہیں رکھتا
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	کال بیک URL توثیق کے دوران مسترد کر دیا گیا
`Address belongs to another user`	ایڈریس کسی دوسرے اکاؤنٹ کے تحت رجسٹرڈ ہے
`Database error adding/updating address`	سرور کی جانب عارضی خرابی — دوبارہ کوشش کریں
`Internal server error`	غیر متوقع خرابی — دوبارہ کوشش کریں یا سپورٹ سے رابطہ کریں

json

{ "code": -1, "msg": "Invalid API key or IP not in whitelist", "data": null }

HTTP اسٹیٹس کوڈز

اینڈپوائنٹ کی خرابیاں HTTP 200 اور ایک منفی code کے ساتھ واپس کی جاتی ہیں — code چیک کریں، HTTP اسٹیٹس کو نہیں۔ خرابی کی باڈیز میں ہمیشہ "data": null شامل ہوتا ہے۔

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

HTTP	باڈی	وجہ
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	اکاؤنٹ کا بیلنس بہت کم ہے
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	API کلید مسدود ہے — سپورٹ سے رابطہ کریں
422	`{"detail": [ … ]}`	درخواست کی باڈی کی توثیق ناکام ہو گئی: کوئی لازمی فیلڈ غائب ہے یا اس کی قسم غلط ہے۔ نوٹ کریں کہ اس رسپانس میں کوئی `code` فیلڈ نہیں ہے

کال بیکس (webhooks)

اگر آپ نے callback_url رجسٹر کیا ہے، تو سسٹم ہر بار جب ایڈریس کو Energy ڈیلیگیٹ کی جاتی ہے اسے کال کرتا ہے (یعنی پروسیس ہونے پر فی ڈیلیگیشن سائیکل ایک بار)۔

درخواست کا فارمیٹ

سسٹم کوئری پیرامیٹرز کے ساتھ ایک HTTP GET درخواست بھیجتا ہے:

USDT ٹرانسفر سے پیدا ہونے والا ایک سائیکل — energy_used موجود ہے:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149936&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=142.3500&idle_cycle=0&energy_used=65k&charged=2.0000

بغیر کسی پچھلے ٹرانسفر کے ایک سائیکل — energy_used کو خارج کر دیا گیا ہے:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149937&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=138.3500&idle_cycle=0&charged=4.0000

پیرامیٹر	تفصیل
address	وہ TRON ایڈریس جس نے Energy کی ڈیلیگیشن حاصل کی
order_id	ڈیلیگیشن شناخت کنندہ (`T` + اندرونی ڈیلیگیشن ID) — فی ڈیلیگیشن منفرد
hash	Energy ڈیلیگیشن کا آن-چین ٹرانزیکشن ہیش
balance_after	اس چارج کے فوری بعد TRX میں آپ کے اکاؤنٹ کا بیلنس (چارج کے وقت کا اسنیپ شاٹ؛ کال بیک موصول ہونے کے وقت تک یہ تبدیل ہو چکا ہو سکتا ہے)
idle_cycle	`1` — یہ ڈیلیگیشن بغیر کسی ٹرانسفر کے 24 گھنٹے گزرنے کے بعد جاری کی گئی تھی (بیکار دوبارہ ڈیلیگیشن)، `0` — آپ کے ٹرانسفر یا ایکٹیویشن سے پیدا ہونے والا باقاعدہ سائیکل
energy_used	اس ٹرانسفر کے ذریعے استعمال ہونے والی Energy کا ٹیرف بینڈ جس نے یہ سائیکل تیار کیا: `65k` (65,000 Energy یا اس سے کم → 2 TRX) یا `131k` (65,000 سے زیادہ → 4 TRX)۔ اختیاری — کوئری اسٹرنگ سے کلید مکمل طور پر خارج کر دی جاتی ہے (خالی نہیں بھیجی جاتی) جب پیمائش کرنے کے لیے کوئی پچھلا ٹرانسفر موجود نہ ہو: ایکٹیویشن کی پہلی ڈیلیگیشن، ہر بیکار دوبارہ ڈیلیگیشن، اور ایسا ایڈریس جس کی ابھی تک کوئی استعمال کی تاریخ نہ ہو۔ ان تمام سے 4 TRX کی شرح سے چارج لیا جاتا ہے
charged	اس سائیکل کے لیے چارج کی گئی رقم TRX میں — `2.0000` یا `4.0000`، جو `energy_used` میں ٹیرف سے مطابقت رکھتی ہے۔ ہمیشہ موجود ہوتی ہے، بشمول تب جب `energy_used` خارج کر دیا گیا ہو۔ دیکھیں Host Mode → Cycles and Pricing

ایک ڈیلیگیشن کو دوسری سے ممتاز کرنے اور اپنے ریکارڈز سے ملانے کے لیے order_id اور hash کا استعمال کریں — ایک ہی ایڈریس کے لیے دو کال بیکس ان ویلیوز سے مختلف ہوتے ہیں۔ /apiv2/time/status کو پول کیے بغیر فی سائیکل خرچ کو ٹریک کرنے کے لیے charged کا استعمال کریں، اور یہ دیکھنے کے لیے کہ پچھلا ٹرانسفر کس ٹیرف میں آیا تھا energy_used کا استعمال کریں۔ energy_used کو ایک اختیاری پیرامیٹر کے طور پر پڑھیں — کلید کے غائب ہونے کا مطلب ہے "پیمائش کے لیے کوئی ٹرانسفر نہیں"، کوئی خرابی نہیں، اور کبھی بھی اس کے لیے پہلے سے طے شدہ قیمت فرض نہ کریں۔

نمونہ ہینڈلر (Python / Flask)

python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['GET'])
def energy_delegation_webhook():
    address = request.args.get('address')
    order_id = request.args.get('order_id')
    tx_hash = request.args.get('hash')
    charged = request.args.get('charged')          # TRX charged for this cycle
    energy_used = request.args.get('energy_used')  # '65k' | '131k' | None (key may be absent)

    if not address:
        return jsonify({"error": "Missing address parameter"}), 400

    # Your business logic (idempotent by order_id / hash)
    print(f"Energy delegated: address={address} order_id={order_id} hash={tx_hash} "
          f"charged={charged} energy_used={energy_used}")
    return jsonify({"status": "success"}), 200

ترسیل کا رویہ (Delivery behaviour)

طریقہ: GET، ٹائم آؤٹ تقریباً 10 سیکنڈ۔ وصولی کی تصدیق کے لیے HTTP 200 واپس کریں۔
دوبارہ کوششیں: اگر درخواست ناکام ہو جاتی ہے تو 3 کوششیں کی جاتی ہیں؛ اگر تمام ناکام ہو جائیں، تو کال بیک کو ڈراپ کر دیا جاتا ہے (Energy کی ڈیلیگیشن بہرحال ہوتی ہے)۔
کوئی دستخط نہیں: درخواست پر Netts کے ذریعے دستخط نہیں کیے جاتے ہیں۔ خفیہ کلید (اگر کوئی ہو) وہی ہے جو آپ نے اپنے callback_url میں شامل کی ہے۔
تصفیہ (Reconciliation): چونکہ کال بیکس چھوٹ سکتے ہیں، اس لیے /apiv2/time/status کو بھی پول کریں اور اپنے ہینڈلر کو آئیڈیمپوٹینٹ (idempotent) بنائیں۔

کال بیک کو اپ ڈیٹ / ہٹانا

اپ ڈیٹ کریں: اسی ایڈریس اور نئے callback_url کے ساتھ دوبارہ /apiv2/time/add کو کال کریں۔
ہٹائیں: ایڈریس کو ہٹانے کے لیے /apiv2/time/delete کو کال کریں (یہ اس کے کال بیک کو بھی ہٹا دیتا ہے)؛ اگر ضرورت ہو تو callback_url کے بغیر دوبارہ شامل کریں۔

نوٹس

نئے ایڈریسز غیر فعال (inactive) شروع ہوتے ہیں؛ انہیں کسی آرڈر کے ساتھ، infinity اسٹارٹ کے ساتھ، یا یہاں "infinity": true پاس کر کے فعال کریں۔
ایک ہی ایڈریس کو دو مختلف اکاؤنٹس کے تحت رجسٹر نہیں کیا جا سکتا۔
ایڈریس کو شامل کرنے سے پہلے TRON نیٹ ورک پر فعال ہونا چاہیے۔

POST /apiv2/time/add ​

اینڈپوائنٹ URL ​

تصدیق (Authentication) ​

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

پیرامیٹرز ​

رویہ (Behaviour) ​

infinity ​

نمونہ درخواستیں ​

cURL ​

Python ​

Node.js ​

رسپانس ​

کامیابی (نیا ایڈریس) ​

کامیابی (موجودہ ایڈریس کے لیے کال بیک URL اپ ڈیٹ ہو گیا) ​

رسپانس فیلڈز ​

خرابی کے رسپانسز ​

HTTP اسٹیٹس کوڈز ​

کال بیکس (webhooks) ​

درخواست کا فارمیٹ ​

نمونہ ہینڈلر (Python / Flask) ​

ترسیل کا رویہ (Delivery behaviour) ​

کال بیک کو اپ ڈیٹ / ہٹانا ​

متعلقہ اینڈپوائنٹس ​

نوٹس ​

POST /apiv2/time/add

اینڈپوائنٹ URL

تصدیق (Authentication)

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

پیرامیٹرز

رویہ (Behaviour)

infinity

نمونہ درخواستیں

cURL

Python

Node.js

رسپانس

کامیابی (نیا ایڈریس)

کامیابی (موجودہ ایڈریس کے لیے کال بیک URL اپ ڈیٹ ہو گیا)

رسپانس فیلڈز

خرابی کے رسپانسز

HTTP اسٹیٹس کوڈز

کال بیکس (webhooks)

درخواست کا فارمیٹ

نمونہ ہینڈلر (Python / Flask)

ترسیل کا رویہ (Delivery behaviour)

کال بیک کو اپ ڈیٹ / ہٹانا

متعلقہ اینڈپوائنٹس

نوٹس