GET /apiv2/balances/

อ่านยอดคงเหลือของที่อยู่ TRON ใดก็ได้: ณ ตอนนี้, ในอดีต, ตามช่วงเวลา หรือสรุปยอดรวมสำหรับรอบระยะเวลา มีทั้งหมด 6 เอ็นด์พอยต์ ซึ่งทำงานแบบซิงโครนัสทั้งหมด — คำตอบจะส่งกลับมาในผลลัพธ์ทันที ไม่มีการเข้าคิวและไม่ต้องคอยส่งคำขอตรวจสอบเป็นระยะ

Base URL ของ Endpoint

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

{address} คือที่อยู่ TRON ในรูปแบบ base58 ความยาว 34 อักขระพอดี

Headers ของคำขอ

Header	Required	Description
X-API-KEY	ใช่	คีย์ API จากแดชบอร์ด
X-Real-IP	ใช่	ที่อยู่ IP จากไวท์ลิสต์ของคีย์

ยอดคงเหลือในบัญชีของคุณต้องมีอย่างน้อย 4 TRX บัญชีที่ยอดเงินหมดจะได้รับคำตอบกลับเป็น 402 ก่อนที่คำขอจะเข้าถึงข้อมูล

เอ็นด์พอยต์ทั้ง 6 รายการ

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" เป็นทศนิยมที่แปลงให้อยู่ในรูปข้อความเพื่อไม่ให้สูญเสียความแม่นยำจากการแปลงทศนิยมแบบ floating-point ให้แยกวิเคราะห์ข้อมูลด้วยชนิดข้อมูล decimal ไม่ใช่ float

ในการตอบกลับเกี่ยวกับข้อมูลในอดีต balance คือคำตอบที่ถูกต้อง ส่วน node_balance ไม่ใช่ balance คือจำนวนเงิน ณ จุดเวลาที่คุณสอบถาม node_balance คือสิ่งที่เชนถือครองอยู่ ณ ตอนนี้ ในทุกการตอบกลับ — ดังนั้นในคำตอบของเดือนที่แล้ว ฟิลด์นี้ก็ยังคงแสดงตัวเลขของวันนี้ ห้ามแสดงค่านี้เป็นจำนวนเงินในอดีตโดยเด็ดขาด สำหรับคำถามเกี่ยวกับข้อมูล ปัจจุบัน บทบาทของทั้งสองฟิลด์จะสลับกัน ซึ่งจะอธิบายในหัวข้อถัดไป

การระบุวันที่หมายถึงการสิ้นสุดของวันนั้น ?on=2026-09-01 จะตอบข้อมูลสำหรับ 2026-09-01 23:59:59Z หากคุณต้องการข้อมูลเริ่มต้นของวัน ให้สอบถามข้อมูลสิ้นสุดของวันก่อนหน้า หรือใช้ /at-block พร้อมระบุ ts แบบเจาะจง

ยอดคงเหลือสองรูปแบบ และเหตุผลที่ยอด "ปัจจุบัน" มีความซับซ้อน

การตอบกลับจะมีตัวเลขสองค่าที่แตกต่างกัน และในที่อยู่ที่มีความเคลื่อนไหว ตัวเลขทั้งสองจะไม่ตรงกัน:

Field	What it is	When it is exact
balance	มูลค่าตามบัญชีแยกประเภท (ledger) ซึ่งสร้างขึ้นใหม่จากเหตุการณ์บนเชนที่จัดทำดัชนีแล้วจนถึงบล็อกที่รายงานใน as_of_block	แม่นยำตรงตามบล็อกนั้น — ซึ่งไม่ใช่บล็อกใหม่ล่าสุด
node_balance	สิ่งที่โหนด TRON ถือครองอยู่ ณ ตอนนี้	เป็นปัจจุบันเสมอ ไม่ใช่ข้อมูลในอดีต

balance ไม่ใช่ "ยอดคงเหลือบนเชน ณ ปัจจุบัน" แต่เป็นยอดคงเหลือ ณ บล็อก as_of_block เมื่อคุณต้องการทราบตัวเลขปัจจุบันของเชน ให้อ่านจาก node_balance — ค่านี้ดึงมาจากโหนด TRON ในเวลาที่มีการส่งคำขอ และสำหรับ TRX จะคำนวณตามสูตรเต็ม: ยอดคงเหลือสภาพคล่อง บวกกับที่สเตกไว้ใน frozenV2 บวกกับยอดที่มอบสิทธิ์ออกไป (delegated) ตัวอย่างเช่น ที่อยู่ที่ถือครอง TRX ที่สเตกไว้ 41.7 ล้าน จะตอบกลับมาเป็น 42035672.226020 ซึ่งตรงกับ 237799.226020 + 41760434 + 36816 + 623 พอดี หากอ่านเพียงฟิลด์ balance ทั่วไปของโหนด จะแสดงเพียง 2.37 แสน และคลาดเคลื่อนไปถึงสองหลักของขนาด

แต่ node_balance ไม่ได้มีข้อมูลครบทุกแถว TRX และ TRC10 ทุกรายการจะถูกส่งกลับมาในการเรียกใช้ getaccount เพียงครั้งเดียว จึงมีข้อมูลนี้เสมอ ส่วน TRC20 ไม่สามารถทำได้: โหนดไม่มีวิธีแสดงรายการโทเค็น TRC20 ทั้งหมดที่ที่อยู่หนึ่งถือครองอยู่ ดังนั้นจึงมีการเรียกสอบถาม balanceOf เฉพาะโทเค็นหลักๆ เท่านั้น จากการวัดผลในวอลเล็ตที่มีแถว TRC20 จำนวน 504 รายการ พบว่า 494 รายการตอบกลับเป็น null ค่า null ดังกล่าวเป็นไปตามนโยบายการทำงานไม่ใช่ข้อผิดพลาด และค่า null เดียวกันนี้จะปรากฏขึ้นหากโหนดไม่สามารถเข้าถึงได้ชั่วคราว ดังนั้นสำหรับ TRX และ TRC10 คุณจะเข้าถึงมูลค่าปัจจุบันของเชนได้เสมอ สำหรับโทเค็น TRC20 ทั่วไป สิ่งที่คุณมีจะมีเพียง balance และบล็อกที่ข้อมูลนั้นอ้างอิงอยู่เท่านั้น

บัญชีแยกประเภทจะเลื่อนไปยังบล็อกใหม่ได้ก็ต่อเมื่อตัวเขียนดัชนีทุกตัวได้ยืนยันบล็อกนั้นแล้ว และขีดกำหนด (watermark) ของระบบจะเป็นค่าต่ำสุดในบรรดาตัวเขียนทั้งหมด ตัวเขียนที่ทำงานช้าที่สุดจะเผยแพร่เครื่องหมายเป็นชุดๆ ช่องว่างของเวลาจึงค่อยๆ กว้างขึ้นแล้วดึงกลับมาทันที — ลักษณะเป็นคลื่นฟันปลา ไม่ใช่ค่าคงที่

ตัวอย่างจากการสุ่มตัวอย่างในช่วงเวลา 20 นาที เมื่อวันที่ 6 กันยายน 2026:

	Blocks behind the head	Time behind
ดีที่สุด	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 ได้ตอบกลับเป็น 766.194807 เมื่อใช้ live=true ในขณะที่โหนดถือครองอยู่ 1698.995472 แม้จะมีประโยชน์ แต่ node_balance ยังคงเป็นฟิลด์เดียวที่แสดงมูลค่าปัจจุบันของเชนอย่างแท้จริง
• คำตอบของข้อมูลในอดีตมีความแม่นยำอย่างสมบูรณ์ /at, /at-block, /history, /summary และ /statement อธิบายจุดเวลาที่บัญชีแยกประเภทผ่านมานานแล้ว จึงไม่มีปัญหาเรื่องความล่าช้าให้ต้องกังวล

สำหรับงานบัญชี การกระทบยอด และรายการเดินบัญชี ให้ใช้เอ็นด์พอยต์ข้อมูลในอดีตและวางใจในความถูกต้องได้ สำหรับหน้าจอแสดงผลวอลเล็ตแบบสด ให้แสดง node_balance ในจุดที่มีข้อมูล — ซึ่งครอบคลุม TRX และ TRC10 ทุกรายการ — และใช้ balance สำรองพร้อมระบุ as_of_block กำกับไว้ข้างๆ ในจุดที่เป็น null เพื่อให้ผู้อ่านทราบว่าตัวเลขดังกล่าวอ้างอิง ณ บล็อกใด

/history จะส่งกลับเฉพาะวันที่มีความเคลื่อนไหวเท่านั้น การขอข้อมูล days=7 สำหรับที่อยู่ที่มีความเคลื่อนไหวเพียง 3 วัน จะได้รับข้อมูลกลับมา 3 จุด ไม่ใช่ 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 จะไม่แย่งโควตากัน

การส่งคำขอเกินขีดจำกัดจะได้รับ 429 พร้อมเฮดเดอร์ Retry-After: 1 ควบคู่กับ RateLimit-Limit, RateLimit-Remaining และ RateLimit-Reset ให้ลองส่งคำขอใหม่อีกครั้งหลังจากระยะเวลาหน่วงที่ระบุ

ขีดจำกัดชั้นที่สองซึ่งกว้างกว่ามากคือ 100 คำขอต่อวินาทีต่อ IP ต้นทาง จะมีผลบังคับใช้ทั่วทั้ง API คุณสามารถแยกความแตกต่างระหว่างสองกรณีนี้ได้จากข้อความ: ขีดจำกัดระดับเอ็นด์พอยต์จะระบุว่า Endpoint rate limit exceeded (10 req/s shared) ส่วนขีดจำกัดระดับบัญชีจะระบุว่า API rate limit exceeded

การตอบกลับเมื่อเกิดข้อผิดพลาด

HTTP	Meaning
400	ที่อยู่มีความยาว 34 อักขระ แต่ผลรวมตรวจสอบ (checksum) ของ base58 ไม่ถูกต้อง
401	คีย์ขาดหายไปหรือไม่ถูกต้อง หรือ IP ต้นทางไม่อยู่ในไวท์ลิสต์
402	ยอดคงเหลือในบัญชีต่ำกว่าขั้นต่ำ 4 TRX
403	คีย์ API ถูกบล็อก โปรดติดต่อฝ่ายสนับสนุน
422	พารามิเตอร์ขาดหายไปหรืออยู่นอกช่วงที่กำหนด — เช่น ความยาวที่อยู่ไม่ถูกต้อง หรือ ops_limit อยู่นอกช่วง 10–5000
429	เกินขีดจำกัดอัตราการส่งคำขอ
503	ระบบคำนวณยอดคงเหลือไม่ตอบสนอง คำขอนี้จะไม่ถูกนับ ให้ลองส่งใหม่อีกครั้ง

เนื้อหาของข้อผิดพลาดจะมาใน 3 รูปแบบ ขึ้นอยู่กับว่าเลเยอร์ใดเป็นผู้ปฏิเสธคำขอ ให้ตรวจสอบเงื่อนไขจากสถานะ 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
• เว็บฮุกรายงาน — การรับการแจ้งเตือนเมื่อไฟล์พร้อมใช้งาน