GET /apiv2/balances/

کسی بھی TRON ایڈریس کا بیلنس پڑھیں: بالکل ابھی، ماضی کے کسی لمحے پر، وقت کے ساتھ، یا کسی مدت کا مجموعہ۔ چھ اینڈ پوائنٹس، تمام سنکرونس — جواب فوراً موصول ہوتا ہے، کوئی قطار نہیں اور پولنگ کی ضرورت نہیں۔

Endpoint base URL

https://netts.io/apiv2/balances/{address}

{address} بیس 58 میں ایک TRON ایڈریس ہے، بالکل 34 حروف پر مشتمل۔

درخواست کے Headers

Header	Required	Description
X-API-KEY	ہاں	ڈیش بورڈ سے API کلید
X-Real-IP	ہاں	کلید کی وائٹ لسٹ سے ایک ایڈریس

آپ کے اکاؤنٹ کا بیلنس کم از کم 4 TRX ہونا چاہیے۔ خالی اکاؤنٹ کو درخواست ڈیٹا تک پہنچنے سے پہلے ہی 402 کے ساتھ جواب دیا جاتا ہے۔

چھ اینڈ پوائنٹس

اینڈ پوائنٹ	جوابات
GET /apiv2/balances/{address}	اس وقت موجود تمام ٹوکنز
GET /apiv2/balances/{address}/at?on=YYYY-MM-DD	اس تاریخ کے اختتام پر بیلنس، UTC
GET /apiv2/balances/{address}/at-block?block=N	ایک قطعی بلاک پر، یا ts=YYYY-MM-DD HH:MM:SS پر بیلنس
GET /apiv2/balances/{address}/history?token_id=TRX&days=90	ایک ٹوکن کی روزانہ کی نقل و حرکت
GET /apiv2/balances/{address}/summary?date_from=&date_to=	ابتدائی، آمد، اخراج، فیس اور اختتامی بیلنس فی ٹوکن
GET /apiv2/balances/{address}/statement?date_from=&date_to=	انفرادی کارروائیوں کے ساتھ اسٹیٹمنٹ کا پیش منظر

مثالیں

curl -s 'https://netts.io/apiv2/balances/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10'

{
  "status": "success",
  "code": 0,
  "msg": "",
  "data": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "as_of_block": 86012345,
    "live": false,
    "hide_spam": false,
    "total_value_usd": "385.25",
    "balances": [
      {
        "token_id": "TRX",
        "symbol": "TRON",
        "token_type": "TRX",
        "decimals": 6,
        "balance": "1141.899000",
        "price_usd": "0.334968",
        "value_usd": "382.50",
        "is_verified": true,
        "is_spam": false,
        "balance_source": "events",
        "node_balance": "1141.899000"
      }
    ]
  }
}

انٹیگریٹ کرنے سے پہلے جاننے کے لائق باتیں

رقم سٹرنگز ہیں، نمبرز نہیں۔ "1141.899000" ایک ڈیسیمل ہے جسے ٹیکسٹ کے طور پر سیریلائز کیا گیا ہے تاکہ فلوٹنگ پوائنٹ کی منتقلی میں درستگی ضائع نہ ہو۔ اسے ڈیسیمل ٹائپ کے ساتھ پارس کریں، فلوٹ کے ساتھ نہیں۔

ماضی سے متعلق جواب میں، balance ہی اصل جواب ہے اور node_balance نہیں۔ balance وہ رقم ہے جس لمحے کے بارے میں آپ نے پوچھا تھا۔ node_balance وہ ہے جو چین پر بالکل ابھی موجود ہے، ہر جواب میں — چنانچہ پچھلے مہینے کے جواب میں بھی یہ آج کی رقم دکھاتا ہے۔ اسے کبھی بھی تاریخی رقم کے طور پر ظاہر نہ کریں۔ ابھی کے سوال کے لیے کردار الٹ جاتے ہیں؛ یہ اگلا حصہ ہے۔

تاریخ کا مطلب اس دن کا اختتام ہے۔ ?on=2026-09-01 جواب دیتا ہے 2026-09-01 23:59:59Z کے لیے۔ اگر آپ کو دن کے آغاز کی ضرورت ہے، تو پچھلے دن کے اختتام کی درخواست کریں، یا واضح ts کے ساتھ /at-block استعمال کریں۔

دو بیلنس، اور "ابھی" کا معاملہ کیوں پیچیدہ ہے

ایک جواب میں دو مختلف نمبرز ہوتے ہیں، اور ایک فعال ایڈریس پر وہ متفق نہیں ہوتے:

فیلڈ	یہ کیا ہے	یہ کب قطعی درست ہوتا ہے
balance	لیجر کی قدر، جو as_of_block میں رپورٹ کیے گئے بلاک تک انڈیکس شدہ چین ایونٹس سے دوبارہ تشکیل دی گئی ہے	اس بلاک کے لیے قطعی درست — جو کہ تازہ ترین بلاک نہیں ہے
node_balance	جو TRON نوڈ پر بالکل ابھی موجود ہے	ہمیشہ موجودہ، کبھی تاریخی نہیں

balance کا مطلب "چین پر بالکل ابھی کا بیلنس" نہیں ہے۔ یہ as_of_block کے وقت کا بیلنس ہے۔ جب آپ کو چین کی موجودہ رقم کی ضرورت ہو، تو node_balance پڑھیں — یہ درخواست کے وقت TRON نوڈ سے لیا جاتا ہے اور، TRX کے لیے، مکمل فارمولے کے ذریعے: مائع بیلنس جمع اسٹیک شدہ frozenV2 جمع جو ڈیلیگیٹ کیا گیا ہے۔ 41.7 ملین اسٹیک شدہ TRX والے ایڈریس پر اس نے جواب دیا 42035672.226020، جو بالکل 237799.226020 + 41760434 + 36816 + 623 ہے۔ صرف نوڈ کی سادہ balance فیلڈ کو پڑھنے سے 237 ہزار ظاہر ہوتا اور یہ دو درجے غلط ہوتا۔

لیکن node_balance ہر قطار کے لیے پُر نہیں ہوتا ہے۔ TRX اور تمام TRC10 ایک ہی getaccount کال میں واپس آتے ہیں، لہذا وہ ہمیشہ اسے رکھتے ہیں۔ TRC20 ایسا نہیں کر سکتا: ایک نوڈ کے پاس TRC20 ٹوکنز کی فہرست بنانے کا کوئی طریقہ نہیں ہے جو ایڈریس کے پاس ہیں، لہذا balanceOf صرف بڑے ٹوکنز کے لیے پوچھا جاتا ہے۔ 504 TRC20 قطاروں والے والیٹ پر جانچنے سے ان میں سے 494 کا جواب null آیا۔ یہ null کسی ناکامی کے بجائے پالیسی ہے، اور یہی null اس وقت بھی ظاہر ہوتا ہے جب نوڈ عارضی طور پر ناقابل رسائی ہو۔ چنانچہ TRX اور TRC10 کے لیے چین کی موجودہ قدر ہمیشہ آپ کے لیے دستیاب ہوتی ہے؛ جبکہ دیگر TRC20 کے لیے آپ کے پاس صرف balance اور وہ بلاک ہے جس پر یہ کھڑا ہے۔

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

6 ستمبر 2026 کو 20 منٹ کی ونڈو میں لیا گیا نمونہ:

	ہیڈ سے پیچھے بلاکس	تاخیر کا وقت
بہترین	22	~1 منٹ
اوسط	44	~2 منٹ
90 واں پرسنٹائل	86	~4 منٹ
بدترین مشاہدہ	121	~6 منٹ

لیجر کے چین سے چند سیکنڈ نہیں بلکہ چند منٹ پیچھے رہنے کا منصوبہ بنائیں۔

اس سے کیا نتائج نکلتے ہیں:

• ایک غیر فعال ایڈریس "ابھی" کے لیے بھی قطعی درست ہے۔ جب موجودہ تاخیر سے زیادہ دیر تک کوئی نقل و حرکت نہ ہوئی ہو، تو لیجر برابر آ جاتا ہے اور balance، node_balance کے برابر ہو جاتا ہے۔
• جس ایڈریس پر ابھی ٹرانزیکشن ہوئی ہو، وہاں balance دونوں سمتوں میں غلط ہو سکتا ہے — جب تک موصول ہونے والی ٹرانسفر ابھی انڈیکس نہ ہوئی ہو تب تک بہت کم، اور جب تک جانے والی ٹرانسفر انڈیکس نہ ہو تب تک بہت زیادہ۔
• live=true خلا کو ختم کیے بغیر کم کر دیتا ہے۔ یہ as_of_block اور چین کے ہیڈ کے درمیان ٹرانسفر ایونٹس کے بقیہ حصے کو فوری طور پر 30–80 ملی سیکنڈ کے لیے لاگو کرتا ہے۔ یہ as_of_block کو تبدیل نہیں کرتا، فیس کا حساب نہیں رکھتا، اور جان بوجھ کر TRC10 ٹوکنز کو نظر انداز کرتا ہے، جنہیں ایک الگ انڈیکس سے ٹریک کیا جاتا ہے۔ ایک ناپی گئی مثال: ایک ایڈریس جس کے لیجر نے 157.317444 TRX رپورٹ کیا، اس نے live=true کے ساتھ 766.194807 کا جواب دیا، جبکہ نوڈ کے پاس 1698.995472 تھا۔ مفید تو ہے، لیکن node_balance ہی وہ واحد فیلڈ رہتی ہے جو چین کی موجودہ قدر ہے۔
• تاریخی جوابات قطعی اور حتمی ہیں۔ /at، /at-block، /history، /summary اور /statement ایسے مقامات کی وضاحت کرتے ہیں جنہیں لیجر نے بہت پہلے پار کر لیا تھا۔ اس میں کسی تاخیر کا حساب نہیں لگانا پڑتا۔

اکاؤنٹنگ، مفاہمت اور اسٹیٹمنٹس کے لیے، تاریخی اینڈ پوائنٹس استعمال کریں اور ان پر بھروسہ کریں۔ لائیو والیٹ اسکرین کے لیے، جہاں موجود ہو وہاں node_balance دکھائیں — جو TRX اور تمام TRC10 کا احاطہ کرتا ہے — اور جہاں یہ null ہو وہاں balance کے ساتھ as_of_block دکھائیں تاکہ پڑھنے والے کو معلوم ہو کہ یہ نمبر کس بلاک پر مبنی ہے۔

/history صرف وہی دن واپس کرتا ہے جن میں سرگرمی ہوئی تھی۔ کسی ایڈریس کے لیے days=7 مانگنا جس میں صرف تین دن نقل و حرکت ہوئی ہو، سات کے بجائے تین پوائنٹس واپس کرتا ہے۔ ہر پوائنٹ اس دن کا اختتامی balance اور پچھلے پوائنٹ کے مقابلے میں delta لاتا ہے۔

/summary خود اپنی مفاہمت کرتا ہے۔ ہر ٹوکن کے لیے opening_balance + period_in − period_out − period_fees = closing_balance، اور انجن یہ حساب پہلے سے control_formula میں لکھ کر واپس کرتا ہے، مثال کے طور پر 76493.940406 + 141490.950160 - 216763.731366 - 79.260200 = 1141.899000۔ فیس کو period_fees_energy اور period_fees_bandwidth میں تقسیم کیا گیا ہے۔ نوٹ کریں کہ /summary کسی ایسے ٹوکن کے لیے تھوڑا منفی بیلنس رپورٹ کر سکتا ہے جسے موجودہ بیلنس کا اینڈ پوائنٹ مکمل طور پر چھوڑ دیتا ہے۔

/statement کو ops_limit کے ذریعے محدود کیا گیا ہے۔ یہ 10 سے 5000 تک کارروائیوں کو قبول کرتا ہے؛ اس حد سے باہر کچھ بھی 422 ہوگا۔ operations_total اس مدت کی اصل تعداد ہے اور operations_truncated بتاتا ہے کہ آیا فہرست مختصر کر دی گئی ہے۔ چھوڑ دیے جانے پر token_id پہلے سے طے شدہ طور پر TRX ہو جاتا ہے۔ 5000 سے زائد کارروائیوں کی مکمل اسٹیٹمنٹ کے لیے، اس کے بجائے فائل کا آرڈر دیں — دیکھیں اسٹیٹمنٹ فائلیں۔

ٹوکن کی ترتیب دانستہ ہے۔ TRX اور بڑے مستحکم کوائنز سب سے پہلے آتے ہیں، پھر تصدیق شدہ ٹوکنز جن کی قیمت ہے، پھر باقی سب کچھ۔ رقم کے لحاظ سے دوبارہ ترتیب نہ دیں: ایئر ڈراپ شدہ اسپام اکثر بڑی برائے نام رقم رکھتا ہے اور سب سے اوپر آ جائے گا۔

اسپام کو نشان زد کیا جاتا ہے، ہٹایا نہیں جاتا۔ is_spam ان ٹوکنز کو جھنڈا لگاتا ہے جنہیں گمراہ کن قرار دیا گیا ہو۔ جواب سے انہیں خارج کرنے کے لیے hide_spam=true پاس کریں؛ TRX اور USDT کو کبھی چھپایا نہیں جاتا۔

شرح کی حدود

ہر اینڈ پوائنٹ 10 درخواستیں فی سیکنڈ قبول کرتا ہے، جو اس اینڈ پوائنٹ کے تمام کلائنٹس میں مشترک ہے۔ حد فی اینڈ پوائنٹ ہے، لہذا /history اور /summary ایک دوسرے کا مقابلہ نہیں کرتے۔

اس سے تجاوز کرنے پر Retry-After: 1 کے ساتھ 429 موصول ہوتا ہے، ساتھ ہی RateLimit-Limit، RateLimit-Remaining اور RateLimit-Reset۔ بتائی گئی تاخیر کے بعد دوبارہ کوشش کریں۔

ایک دوسری، کہیں وسیع حد پوری API پر فی سورس IP 100 درخواستیں فی سیکنڈ لاگو ہوتی ہے۔ دونوں میں میسج سے فرق کیا جاتا ہے: اینڈ پوائنٹ کی حد کہتی ہے Endpoint rate limit exceeded (10 req/s shared)، جبکہ پورے اکاؤنٹ والی کہتی ہے API rate limit exceeded۔

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

HTTP	معنی
400	ایڈریس 34 حروف پر مشتمل ہے لیکن اس کا base58 چیک سم ناکام ہو جاتا ہے
401	کلید غائب یا غلط ہے، یا سورس IP وائٹ لسٹ میں نہیں ہے
402	اکاؤنٹ کا بیلنس 4 TRX کی کم از کم حد سے کم ہے
403	API کلید مسدود ہے؛ سپورٹ سے رابطہ کریں
422	پیرامیٹر غائب ہے یا حد سے باہر ہے — غلط ایڈریس کی لمبائی، یا 10–5000 سے باہر ops_limit
429	شرح کی حد سے تجاوز کر گیا
503	بیلنس انجن نے جواب نہیں دیا؛ درخواست شمار نہیں ہوئی، دوبارہ کوشش کریں

خرابی کے باڈیز تین شکلوں میں آتے ہیں، اس بات پر منحصر ہے کہ کس پرت نے درخواست کو مسترد کیا۔ باڈی پر نہیں، بلکہ HTTP اسٹیٹس پر انحصار کریں۔

// 401, 402, 403 — گیٹ وے، درخواست سروس تک پہنچنے سے پہلے
{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}

// 400, 422 — سروس، پیرامیٹرز پارس ہونے کے بعد
{"status": "error", "code": -4, "msg": "address must be base58 (T...)", "data": {"code": -4, "msg": "address must be base58 (T...)"}}

// 429 — ریٹ لمیٹر
{"message": "Endpoint rate limit exceeded (10 req/s shared), retry shortly", "request_id": "e5dbf25437d2eb215c764617d50b8d3b"}

متعلقہ

• اسٹیٹمنٹ فائلیں — مکمل اسٹیٹمنٹ بطور CSV یا PDF فائل
• رپورٹ ویب ہکس — فائل تیار ہونے پر اطلاع موصول کرنا