Time Status API

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

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

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

POST /apiv2/time/status

Endpoint URL

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

تصدیق (Authentication)

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

Request باڈی

json

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

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

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

مثالیں

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
}

خلاصہ کے فیلڈز

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

order_statistics کے فیلڈز

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

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

فیلڈ	قسم	تفصیل
address	string	TRON ایڈریس
status	string	`"active"` یا `"inactive"`
mode	string	`"normal"`, `"infinity"`، یا `"off"` (جب غیر فعال ہو)
cycles_ordered	integer \| null	کھلے آرڈرز میں آرڈر کیے گئے سائیکلز۔ infinity موڈ میں `null`
cycle_set	integer	ایڈریس کے لیے محفوظ کردہ `cycle_set` کی قیمت
cycles_completed	integer	ایڈریس کو آخری بار شروع کیے جانے کے بعد سے استعمال شدہ سائیکلز۔ جب آپ موڈ روک دیتے ہیں یا آرڈر کیے گئے سائیکلز ختم ہو جاتے ہیں تو دوبارہ صفر ہو جاتا ہے
cycles_remaining	integer \| null	`cycles_ordered − cycles_completed`۔ infinity موڈ میں `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 دیکھ سکتے ہیں۔

خرابی کے Responses

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

msg	وجہ
`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/

ایک ایڈریس کا اسٹیٹس۔

Endpoint URL

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

تصدیق (Authentication)

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

Example Requests

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 وہی فیلڈز استعمال کرتا ہے جو اوپر ایڈریس آبجیکٹ میں دیے گئے ہیں۔

خرابی کے Responses

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

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

نوٹس

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

Time Status API ​

POST /apiv2/time/status ​

Endpoint URL ​

تصدیق (Authentication) ​

Request باڈی ​

مثالیں ​

جواب ​

خلاصہ کے فیلڈز ​

order_statistics کے فیلڈز ​

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

خرابی کے Responses ​

GET /apiv2/time/status/ ​

Endpoint URL ​

تصدیق (Authentication) ​

Example Requests ​

جواب ​

خرابی کے Responses ​

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

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

نوٹس ​

Time Status API

POST /apiv2/time/status

Endpoint URL

تصدیق (Authentication)

Request باڈی

مثالیں

جواب

خلاصہ کے فیلڈز

order_statistics کے فیلڈز

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

خرابی کے Responses

GET /apiv2/time/status/

Endpoint URL

تصدیق (Authentication)

Example Requests

جواب

خرابی کے Responses

HTTP اسٹیٹس کوڈز

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

نوٹس