GET /apiv2/balances/

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

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

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

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

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

ہیڈر	درکار ہے	تفصیل
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 کے لیے، مکمل فارمولے کے مطابق: مائع (liquid) بیلنس جمع اسٹیک شدہ 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 اور وہ بلاک ہے جس پر یہ کھڑا ہے۔

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

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

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

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

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

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

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

/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 اور بڑے مستحکم کوائنز (stablecoins) پہلے آتے ہیں، پھر تصدیق شدہ ٹوکن جن کی قیمت ہے، پھر باقی سب کچھ۔ رقم کے لحاظ سے دوبارہ ترتیب نہ دیں: ایئر ڈراپ کردہ اسپام اکثر بہت زیادہ نامیاتی بیلنس لاتے ہیں اور اوپر تیرنے لگیں گے۔

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

شرح کی حدیں (Rate limits)

ہر اینڈ پوائنٹ 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۔

نقائص (Errors)

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

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

// 401, 402, 403 — the gateway, before the request reaches the service
{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}

// 400, 422 — the service, after parameters are parsed
{"status": "error", "code": -4, "msg": "address must be base58 (T...)", "data": {"code": -4, "msg": "address must be base58 (T...)"}}

// 429 — the rate limiter
{"message": "Endpoint rate limit exceeded (10 req/s shared), retry shortly", "request_id": "e5dbf25437d2eb215c764617d50b8d3b"}

متعلقہ

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