Time Status API

Host Mode میں ایڈریسز کی صورتحال کی معلومات حاصل کریں — اپنے اکاؤنٹ کے تمام ایڈریسز کے لیے، یا کسی ایک ایڈریس کے لیے۔

دو اینڈ پوائنٹس دستیاب ہیں:

POST /apiv2/time/status — آپ کے تمام ایڈریسز کی صورتحال (اختیاری صفحہ بندی اور اکاؤنٹ کی سطح کے خلاصے کے ساتھ)۔
GET /apiv2/time/status/{address} — کسی ایک مخصوص ایڈریس کی صورتحال۔

POST /apiv2/time/status

اینڈ پوائنٹ URL

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

تصدیق (Authentication)

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

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

json

{
    "api_key": "your_api_key",
    "page": 1,
    "page_size": 50
}

پیرامیٹر (Parameter)	قسم (Type)	درکار (Required)	تفصیل (Description)
api_key	string	ہاں	API کلید (یا `X-API-KEY` ہیڈر)۔
page	integer	نہیں	صفحہ نمبر، ≥ 1۔ اس کے لیے `page_size` درکار ہے۔
page_size	integer	نہیں	فی صفحہ ایڈریسز، 1–100۔ اس کے لیے `page` درکار ہے۔

صفحہ بندی (Pagination): اگر page اور page_size دونوں فراہم کیے جائیں، تو نتائج کو صفحات میں تقسیم کیا جاتا ہے اور ایک pagination آبجیکٹ شامل کیا جاتا ہے۔ ان کے بغیر، تمام ایڈریسز (1000 تک) واپس کیے جاتے ہیں، جو تخلیق کے وقت کے لحاظ سے ترتیب دیے گئے ہوتے ہیں (سب سے نئے پہلے)۔

درخواست کی مثالیں (Examples)

cURL (تمام ایڈریسز):

bash

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_API_KEY_HERE" }'

cURL (صفحہ بندی کے ساتھ):

bash

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_API_KEY_HERE", "page": 1, "page_size": 50 }'

Python:

python

import requests

resp = requests.post(
    "https://netts.io/apiv2/time/status",
    json={"api_key": "YOUR_API_KEY_HERE"},  # add "page"/"page_size" to paginate
    timeout=30,
)
result = resp.json()

if result["code"] == 0:
    for a in result["data"]["addresses"]:
        # cycles_remaining is None in infinity mode — no limit to count down
        left = "unlimited" if a["cycles_remaining"] is None else f"{a['cycles_remaining']} left"
        print(a["address"], a["mode"], a["status"], left,
              f"spent {a['total_spent']} TRX")
else:
    print("Error:", result["msg"])

Node.js:

javascript

const axios = require('axios');

axios.post('https://netts.io/apiv2/time/status', { api_key: 'YOUR_API_KEY_HERE' })
    .then(({ data: result }) => {
        if (result.code === 0) {
            result.data.addresses.forEach(a => {
                // cycles_remaining is null in infinity mode — no limit to count down
                const left = a.cycles_remaining === null ? 'unlimited' : `${a.cycles_remaining} left`;
                console.log(a.address, a.mode, a.status, left, `spent ${a.total_spent} TRX`);
            });
        } else {
            console.error('Error:', result.msg);
        }
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

جواب

json

{
    "code": 0,
    "msg": "Status retrieved successfully",
    "data": {
        "summary": {
            "total_addresses": 3,
            "active_addresses": 2,
            "infinity_mode_count": 1,
            "total_cycles_ordered": 25,
            "total_open_orders": 3
        },
        "order_statistics": {
            "total_orders": 12,
            "open_orders": 3,
            "closed_orders": 9,
            "total_cycles_in_open_orders": 25,
            "total_delegations": 340,
            "total_amount_spent": 1502.4471
        },
        "addresses": [
            {
                "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                "status": "active",
                "mode": "normal",
                "cycles_ordered": 25,
                "cycle_set": 25,
                "cycles_completed": 10,
                "cycles_remaining": 15,
                "cycles_total_lifetime": 214,
                "current_cycle_no": 3,
                "open_orders": 1,
                "total_spent": 962.1184,
                "bandwidth_delegated": true,
                "created_at": "2026-07-08T12:00:00.000000",
                "updated_at": "2026-07-09T10:00:00.000000"
            },
            {
                "address": "TYn8Y3khEsLJW2ChVWFMSMeRDow6KcbMTF",
                "status": "active",
                "mode": "infinity",
                "cycles_ordered": null,
                "cycle_set": 0,
                "cycles_completed": 83,
                "cycles_remaining": null,
                "cycles_total_lifetime": 115,
                "current_cycle_no": 5,
                "open_orders": 1,
                "total_spent": 519.1234,
                "bandwidth_delegated": true,
                "created_at": "2026-07-08T08:00:00.000000",
                "updated_at": "2026-07-09T09:30:00.000000"
            }
        ],
        "timestamp": "2026-07-09T12:34:50.123456"
    }
}

صفحہ بندی کے ساتھ، data میں یہ بھی شامل ہوتا ہے:

json

"pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
}

خلاصہ کے فیلڈز (Summary fields)

فیلڈ (Field)	تفصیل (Description)
total_addresses	آپ کے اکاؤنٹ کے تحت ایڈریسز کی تعداد
active_addresses	وہ ایڈریسز جو فی الوقت فعال ہیں
infinity_mode_count	فعال ایڈریسز جو infinity mode میں چل رہے ہیں
total_cycles_ordered	کھلے آرڈرز کے تمام آرڈر شدہ سائیکلز کا مجموعہ (infinity آرڈرز شامل نہیں ہیں)
total_open_orders	تمام ایڈریسز میں کھلے آرڈرز کی تعداد

order_statistics کے فیلڈز

فیلڈ (Field)	تفصیل (Description)
total_orders	اب تک بنائے گئے تمام آرڈرز
open_orders	فی الوقت کھلے آرڈرز
closed_orders	بند شدہ آرڈرز
total_cycles_in_open_orders	کھلے آرڈرز کے سائیکلز (infinity شامل نہیں ہے)
total_delegations	آپ کے تمام ایڈریسز پر درحقیقت کی جانے والی ڈیلیگیشنز
total_amount_spent	حقیقی طور پر وصول کردہ رقم، TRX میں — وہ رقم جو درحقیقت آپ کے بیلنس سے کاٹی گئی

Address آبجیکٹ کے فیلڈز

فیلڈ (Field)	قسم (Type)	تفصیل (Description)
address	string	TRON ایڈریس
status	string	`"active"` یا `"inactive"`
mode	string	`"normal"`, `"infinity"`, یا `"off"` (غیر فعال ہونے پر)
cycles_ordered	integer \| null	کھلے آرڈرز میں آرڈر شدہ سائیکلز۔ infinity mode میں `null`
cycle_set	integer	ایڈریس کے لیے محفوظ کردہ `cycle_set` کی قدر
cycles_completed	integer	ایڈریس کے آخری بار شروع ہونے کے بعد سے استعمال شدہ سائیکلز۔ جب آپ موڈ روکتے ہیں یا آرڈر شدہ سائیکلز ختم ہو جاتے ہیں تو یہ دوبارہ صفر ہو جاتا ہے
cycles_remaining	integer \| null	`cycles_ordered − cycles_completed`۔ infinity mode میں `null`
cycles_total_lifetime	integer	اپنی پوری تاریخ کے دوران اس ایڈریس کے لیے کی گئی تمام ڈیلیگیشنز۔ کبھی ری سیٹ نہیں ہوتا
current_cycle_no	integer \| null	ایڈریس کے آخری بار شروع ہونے کے بعد سے موجودہ ڈیلیگیشن کی پوزیشن۔ جب کوئی ڈیلیگیشن فعال نہ ہو تو `null`
open_orders	integer	ایڈریس کے لیے کھلے آرڈرز کی تعداد
total_spent	number	اس ایڈریس کے لیے درحقیقت وصول کی گئی رقم، TRX میں
bandwidth_delegated	boolean	آیا Bandwidth فی الوقت ڈیلیگیٹ کی گئی ہے۔ Bandwidth مفت ہے اور سائیکل کی قیمت میں شامل ہے
created_at	string	شامل کیے جانے کا ISO ٹائم اسٹیمپ
updated_at	string	آخری اپ ڈیٹ کا ISO ٹائم اسٹیمپ

Infinity mode۔ cycles_ordered اور cycles_remaining کی قدر null ہوتی ہے، 0 نہیں — کیونکہ الٹی گنتی کے لیے کوئی حد مقرر نہیں ہے۔ null کو "لامحدود" سمجھیں، اور اسے "کوئی سائیکل باقی نہیں بچا" کے طور پر نہ پڑھیں۔ cycles_completed پھر بھی ایک حقیقی تعداد ظاہر کرتا ہے۔

تین سائیکل کاؤنٹرز، تین مختلف معانی۔ cycles_completed صرف اس وقت سے گنتی کرتا ہے جب ایڈریس آخری بار شروع ہوا تھا، cycles_total_lifetime اس کی پوری تاریخ کو شمار کرتا ہے، اور current_cycle_no موجودہ ڈیلیگیشن کی پوزیشن ظاہر کرتا ہے۔ ان کا مختلف ہونا متوقع ہے — ایک ہی ایڈریس کے لیے آپ بیک وقت 83، 115 اور 5 دیکھ سکتے ہیں۔

نقائص (Errors)

تمام نقائص code = -1 استعمال کرتے ہیں:

msg	وجہ (Cause)
`API key required in body or X-API-KEY header`	کوئی API کلید فراہم نہیں کی گئی
`Invalid API key or IP not in whitelist`	تصدیق ناکام ہو گئی
`Page number must be >= 1`	`page` 1 سے کم ہے
`Page size must be >= 1`	`page_size` 1 سے کم ہے
`Page size must be <= 100`	`page_size` 100 سے زیادہ ہے
`Database error getting status`	عارضی سرور سائیڈ خرابی — دوبارہ کوشش کریں
`Internal server error`	غیر متوقع خرابی — دوبارہ کوشش کریں یا سپورٹ سے رابطہ کریں

GET /apiv2/time/status/

کسی ایک ایڈریس کی صورتحال۔

اینڈ پوائنٹ URL

GET https://netts.io/apiv2/time/status/{address}

تصدیق (Authentication)

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

درخواست کی مثال (Examples)

bash

curl -X GET "https://netts.io/apiv2/time/status/TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" \
  -H "X-API-KEY: YOUR_API_KEY_HERE"

python

import requests

address = "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
resp = requests.get(
    f"https://netts.io/apiv2/time/status/{address}",
    headers={"X-API-KEY": "YOUR_API_KEY_HERE"},
    timeout=30,
)
print(resp.json())

جواب

json

{
    "code": 0,
    "msg": "Address status retrieved successfully",
    "data": {
        "address_info": {
            "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "status": "active",
            "mode": "normal",
            "cycles_ordered": 25,
            "cycle_set": 25,
            "cycles_completed": 10,
            "cycles_remaining": 15,
            "cycles_total_lifetime": 214,
            "current_cycle_no": 3,
            "open_orders": 1,
            "total_spent": 962.1184,
            "bandwidth_delegated": true,
            "created_at": "2026-07-08T12:00:00.000000",
            "updated_at": "2026-07-09T10:00:00.000000"
        },
        "timestamp": "2026-07-09T12:34:50.123456"
    }
}

address_info وہی فیلڈز استعمال کرتا ہے جو اوپر ایڈریس آبجیکٹ میں دیے گئے ہیں۔

نقائص (Errors)

code = -1، مثال کے طور پر:

msg	وجہ (Cause)
`API key required in X-API-KEY header`	غائب ہیڈر
`Invalid API key or IP not in whitelist`	تصدیق ناکام ہو گئی
`Address not found or doesn't belong to user`	اس اکاؤنٹ کے لیے نامعلوم ایڈریس
`Database error getting address status`	عارضی سرور سائیڈ خرابی — دوبارہ کوشش کریں
`Internal server error`	غیر متوقع خرابی — دوبارہ کوشش کریں یا سپورٹ سے رابطہ کریں

HTTP اسٹیٹس کوڈز (HTTP status codes)

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

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

HTTP	باڈی (Body)	وجہ (Cause)
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 کلید مسدود (blocked) ہے — سپورٹ سے رابطہ کریں
422	`{"detail": [ … ]}`	صرف POST — درخواست کے باڈی کی توثیق ناکام ہو گئی: کسی فیلڈ کی قسم غلط ہے، یا `page`/`page_size` کو بغیر `api_key` کے بھیجا گیا تھا۔ نوٹ کریں کہ اس رسپانس میں کوئی `code` فیلڈ نہیں ہے

POST /apiv2/time/add — ایڈریس شامل کریں
POST /apiv2/time/order — سائیکلز خریدیں
POST /apiv2/time/infinitystart — infinity mode فعال کریں
POST /apiv2/time/stop — ایڈریس کو روکیں
POST /apiv2/time/delete — ایڈریس کو حذف کریں

نوٹس (Notes)

صورتحال کے اینڈ پوائنٹس صرف پڑھنے کے لیے (read-only) ہیں۔
صرف وہی ایڈریسز واپس کیے جاتے ہیں جو آپ کے اکاؤنٹ سے تعلق رکھتے ہیں۔
ٹائم اسٹیمپ ISO 8601 اسٹرنگز پر مشتمل ہیں۔

Time Status API ​

POST /apiv2/time/status ​

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

تصدیق (Authentication) ​

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

درخواست کی مثالیں (Examples) ​

جواب ​

خلاصہ کے فیلڈز (Summary fields) ​

order_statistics کے فیلڈز ​

Address آبجیکٹ کے فیلڈز ​

نقائص (Errors) ​

GET /apiv2/time/status/ ​

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

تصدیق (Authentication) ​

درخواست کی مثال (Examples) ​

جواب ​

نقائص (Errors) ​

HTTP اسٹیٹس کوڈز (HTTP status codes) ​

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

نوٹس (Notes) ​

Time Status API

POST /apiv2/time/status

اینڈ پوائنٹ URL

تصدیق (Authentication)

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

درخواست کی مثالیں (Examples)

جواب

خلاصہ کے فیلڈز (Summary fields)

order_statistics کے فیلڈز

Address آبجیکٹ کے فیلڈز

نقائص (Errors)

GET /apiv2/time/status/

اینڈ پوائنٹ URL

تصدیق (Authentication)

درخواست کی مثال (Examples)

جواب

نقائص (Errors)

HTTP اسٹیٹس کوڈز (HTTP status codes)

متعلقہ اینڈ پوائنٹس (Related Endpoints)

نوٹس (Notes)