GET /apiv2/balances/

किसी भी TRON पते के बैलेंस पढ़ें: अभी, किसी पिछले समय पर, समय के साथ, या किसी अवधि के लिए कुल जोड़। छह एंडपॉइंट्स, सभी सिंक्रोनस — उत्तर सीधे रिप्लाई में आता है, कोई कतार (queue) नहीं है और पोल (poll) करने के लिए कुछ भी नहीं है।

एंडपॉइंट बेस URL

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

{address} base58 में एक TRON पता है, ठीक 34 वर्णों का।

अनुरोध हेडर

Header	Required	Description
X-API-KEY	हाँ	डैशबोर्ड से प्राप्त API कुंजी
X-Real-IP	हाँ	कुंजी व्हाइटलिस्ट से एक पता

आपके खाते का बैलेंस कम से कम 4 TRX होना चाहिए। अनुरोध डेटा तक पहुँचने से पहले ही एक समाप्त बैलेंस वाले खाते को 402 के साथ उत्तर दिया जाता है।

छह एंडपॉइंट्स

Endpoint	Answers
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" टेक्स्ट के रूप में क्रमबद्ध (serialised) एक दशमलव है ताकि फ्लोटिंग-पॉइंट राउंड ट्रिप में कोई सटीकता न खोए। इसे फ्लोट के बजाय दशमलव प्रकार (decimal type) के साथ पार्स करें।

अतीत के बारे में रिप्लाई में, balance ही उत्तर है और node_balance नहीं है। balance उस बिंदु पर राशि है जिसके बारे में आपने पूछा था। node_balance वह है जो चेन में अभी मौजूद है, हर रिप्लाई में — इसलिए पिछले महीने के बारे में किसी उत्तर में यह अभी भी आज की संख्या दिखाता है। इसे कभी भी ऐतिहासिक राशि के रूप में प्रदर्शित न करें। अभी के बारे में पूछे गए प्रश्न के लिए भूमिकाएँ बदल जाती हैं; यह अगला अनुभाग है।

एक तारीख का अर्थ है उस दिन का अंत। ?on=2026-09-01 का उत्तर 2026-09-01 23:59:59Z के लिए होता है। यदि आपको किसी दिन की शुरुआत की आवश्यकता है, तो पिछले दिन के अंत के लिए पूछें, या एक स्पष्ट ts के साथ /at-block का उपयोग करें।

दो बैलेंस, और "अभी" वाला पेचीदा क्यों है

एक रिप्लाई में दो अलग-अलग संख्याएँ होती हैं, और एक सक्रिय पते पर वे मेल नहीं खाती हैं:

Field	What it is	When it is exact
balance	लेज़र मान, जिसे as_of_block में रिपोर्ट किए गए ब्लॉक तक अनुक्रमित (indexed) चेन घटनाओं से पुनर्गठित किया गया है	उस ब्लॉक के लिए सटीक — जो कि सबसे नया ब्लॉक नहीं है
node_balance	एक TRON नोड में अभी क्या मौजूद है	हमेशा वर्तमान, कभी ऐतिहासिक नहीं

balance का अर्थ "चेन पर अभी का बैलेंस" नहीं है। यह as_of_block के समय का बैलेंस है। जब आपको चेन की वर्तमान संख्या की आवश्यकता हो, तो node_balance पढ़ें — यह अनुरोध के समय एक TRON नोड से लिया जाता है और, TRX के लिए, पूर्ण सूत्र द्वारा: लिक्विड बैलेंस प्लस स्टेक किया गया frozenV2 प्लस जो बाहर डेलिगेट किया गया है। 41.7 मिलियन स्टेक किए गए TRX रखने वाले पते पर इसने 42035672.226020 उत्तर दिया, जो बिल्कुल 237799.226020 + 41760434 + 36816 + 623 है। केवल नोड के सामान्य balance फ़ील्ड को पढ़ने पर 237 हज़ार दिखाई देता और यह परिमाण के दो क्रमों (two orders of magnitude) से गलत होता।

लेकिन node_balance प्रत्येक पंक्ति के लिए भरा नहीं जाता है। TRX और प्रत्येक TRC10 एक getaccount कॉल में वापस आते हैं, इसलिए वे इसे हमेशा साथ रखते हैं। TRC20 ऐसा नहीं कर सकता: किसी पते पर मौजूद TRC20 टोकन को सूचीबद्ध करने का नोड के पास कोई तरीका नहीं है, इसलिए केवल प्रमुख टोकन के लिए ही balanceOf पूछा जाता है। 504 TRC20 पंक्तियों वाले वॉलेट पर मापे जाने पर, उनमें से 494 null वापस आए। वह null विफलता के बजाय एक नीति है, और यदि नोड थोड़े समय के लिए अगम्य हो तो वही null दिखाई देता है। इसलिए TRX और TRC10 के लिए चेन का वर्तमान मान आपके लिए हमेशा उपलब्ध है; एक लॉन्ग-टेल TRC20 के लिए आपके पास केवल balance और वह ब्लॉक है जिस पर वह स्थित है।

लेज़र किसी ब्लॉक पर केवल तभी आगे बढ़ता है जब प्रत्येक इंडेक्सिंग राइटर ने उस ब्लॉक की पुष्टि कर दी हो, और इसका वॉटरमार्क उन सभी में न्यूनतम होता है। सबसे धीमे राइटर्स अपने मार्क्स बैचों में प्रकाशित करते हैं, इसलिए अंतर लगातार बढ़ता है और फिर अचानक वापस आ जाता है — यह एक सॉटूथ (sawtooth) है, कोई स्थिर मान नहीं।

6 सितंबर 2026 को 20 मिनट की विंडो में नमूना लिया गया:

	Blocks behind the head	Time behind
सर्वश्रेष्ठ	22	~1 मिनट
माध्यिका (Median)	44	~2 मिनट
90वाँ पर्सेंटाइल	86	~4 मिनट
सबसे खराब देखा गया	121	~6 मिनट

लेज़र के चेन से कुछ सेकंड नहीं, बल्कि कुछ मिनट पीछे रहने की योजना बनाएं।

इससे निम्नलिखित परिणाम निकलते हैं:

• एक शांत पता "अभी" के लिए भी सटीक होता है। जब वर्तमान अंतराल से अधिक समय तक कुछ भी स्थानांतरित नहीं हुआ हो, तो लेज़र पकड़ बना लेता है और balance का मान node_balance के बराबर हो जाता है।
• एक ऐसे पते पर जिसने अभी-अभी लेन-देन किया है, balance किसी भी दिशा में गलत हो सकता है — जब तक कोई इनकमिंग ट्रांसफर अभी भी गैर-अनुक्रमित (unindexed) है तब तक बहुत कम, और जब तक कोई आउटगोइंग ट्रांसफर अनुक्रमित नहीं है तब तक बहुत अधिक।
• 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 ऑपरेशंस से अधिक के पूर्ण विवरण के लिए, इसके बजाय एक फ़ाइल ऑर्डर करें — देखें Statement files।

टोकन का क्रम जानबूझकर रखा गया है। TRX और प्रमुख स्टेबलकॉइन्स पहले आते हैं, फिर सत्यापित टोकन जिनकी कीमत होती है, फिर बाकी सब कुछ। राशि के अनुसार पुन: क्रमबद्ध न करें: एयरड्रॉप किए गए स्पैम में अक्सर भारी नाममात्र बैलेंस होते हैं और वे शीर्ष पर आ जाएंगे।

स्पैम को चिह्नित किया जाता है, हटाया नहीं जाता। is_spam भ्रामक के रूप में वर्गीकृत टोकन को फ़्लैग करता है। उन्हें रिप्लाई से हटाने के लिए hide_spam=true पास करें; TRX और USDT को कभी भी छिपाया नहीं जाता है।

दर सीमाएं

प्रत्येक एंडपॉइंट 10 अनुरोध प्रति सेकंड स्वीकार करता है, जो उस एंडपॉइंट के सभी क्लाइंट्स के बीच साझा होता है। सीमा प्रति एंडपॉइंट है, इसलिए /history और /summary एक दूसरे के साथ प्रतिस्पर्धा नहीं करते हैं।

इससे अधिक होने पर RateLimit-Limit, RateLimit-Remaining और RateLimit-Reset के साथ Retry-After: 1 के साथ 429 मिलता है। बताए गए विलंब के बाद पुन: प्रयास करें।

प्रति स्रोत IP 100 अनुरोध प्रति सेकंड की एक दूसरी, बहुत व्यापक सीमा पूरे API पर लागू होती है। दोनों को संदेश द्वारा पहचाना जाता है: एंडपॉइंट सीमा कहती है Endpoint rate limit exceeded (10 req/s shared), खाता-व्यापी सीमा कहती है API rate limit exceeded।

त्रुटि प्रतिक्रियाएं

HTTP	Meaning
400	पता 34 वर्णों का है लेकिन इसका base58 चेकसम विफल रहता है
401	कुंजी गायब या अमान्य है, या स्रोत IP व्हाइटलिस्टेड नहीं है
402	खाता बैलेंस 4 TRX न्यूनतम से कम है
403	API कुंजी ब्लॉक है; सहायता टीम से संपर्क करें
422	कोई पैरामीटर गायब है या सीमा से बाहर है — गलत पते की लंबाई, या 10–5000 से बाहर एक ops_limit
429	दर सीमा पार हो गई
503	बैलेंस इंजन ने उत्तर नहीं दिया; अनुरोध की गणना नहीं की गई थी, पुन: प्रयास करें

त्रुटि बॉडी (Error bodies) तीन रूपों में आती हैं, यह इस बात पर निर्भर करता है कि किस लेयर ने अनुरोध को अस्वीकार कर दिया। बॉडी पर नहीं, बल्कि 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"}

संबंधित

• Statement files — CSV या PDF फ़ाइल के रूप में पूर्ण विवरण
• Report webhooks — फ़ाइल तैयार होने पर सूचित किया जाना