GET /apiv2/balances/

Đọc số dư của bất kỳ địa chỉ TRON nào: ngay hiện tại, tại một thời điểm trong quá khứ, theo thời gian, hoặc tổng hợp cho một khoảng thời gian. Sáu endpoint, tất cả đều đồng bộ — kết quả trả về ngay trong phản hồi, không có hàng đợi và không cần thăm dò (poll).

URL gốc của endpoint

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

{address} là một địa chỉ TRON ở định dạng base58, chính xác 34 ký tự.

Tiêu đề yêu cầu

Tiêu đề	Bắt buộc	Mô tả
X-API-KEY	có	Khóa API từ trang quản trị
X-Real-IP	có	Một địa chỉ thuộc danh sách trắng của khóa

Số dư tài khoản của bạn phải có ít nhất 4 TRX. Tài khoản cạn kiệt tiền sẽ nhận phản hồi 402 trước khi yêu cầu tiếp cận được dữ liệu.

Sáu endpoint

Endpoint	Trả lời
GET /apiv2/balances/{address}	mọi token đang nắm giữ ngay hiện tại
GET /apiv2/balances/{address}/at?on=YYYY-MM-DD	số dư tại thời điểm kết thúc ngày đó, UTC
GET /apiv2/balances/{address}/at-block?block=N	số dư tại một block chính xác, hoặc tại ts=YYYY-MM-DD HH:MM:SS
GET /apiv2/balances/{address}/history?token_id=TRX&days=90	biến động của một token, từng ngày một
GET /apiv2/balances/{address}/summary?date_from=&date_to=	số dư đầu kỳ, dòng tiền vào, dòng tiền ra, phí và số dư cuối kỳ cho từng token
GET /apiv2/balances/{address}/statement?date_from=&date_to=	xem trước sao kê với từng hoạt động riêng lẻ

Ví dụ

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"
      }
    ]
  }
}

Những điều đáng lưu ý trước khi bạn tích hợp

Các số tiền là chuỗi ký tự, không phải dạng số. "1141.899000" là một số thập phân được tuần tự hóa dưới dạng văn bản để không bị mất độ chính xác do chuyển đổi số thực dấu phẩy động. Hãy phân tích nó bằng kiểu dữ liệu số thập phân (decimal), không dùng float.

Trong câu trả lời về quá khứ, balance là kết quả cần lấy còn node_balance thì không. balance là số tiền tại thời điểm bạn yêu cầu. node_balance là những gì chuỗi đang nắm giữ ngay hiện tại, trong mọi phản hồi — do đó trong kết quả về tháng trước, nó vẫn hiển thị số của ngày hôm nay. Không bao giờ hiển thị nó làm số tiền lịch sử. Đối với câu hỏi về hiện tại, vai trò sẽ hoán đổi; nội dung đó nằm ở phần tiếp theo.

Một ngày có nghĩa là thời điểm kết thúc của ngày đó. ?on=2026-09-01 trả về kết quả cho 2026-09-01 23:59:59Z. Nếu bạn cần thời điểm đầu ngày, hãy yêu cầu thời điểm cuối của ngày hôm trước, hoặc sử dụng /at-block với ts rõ ràng.

Hai số dư, và lý do vì sao "hiện tại" lại phức tạp

Một phản hồi mang hai con số khác nhau, và trên một địa chỉ đang hoạt động chúng không khớp nhau:

Trường	Ý nghĩa	Thời điểm chính xác
balance	Giá trị sổ cái, được tái tạo lại từ các sự kiện chuỗi đã lập chỉ mục cho đến block được báo cáo trong as_of_block	Chính xác cho block đó — vốn không phải là block mới nhất
node_balance	Những gì một node TRON nắm giữ ngay hiện tại	Luôn là hiện tại, không bao giờ là lịch sử

balance không phải là "số dư trên chuỗi ngay hiện tại". Nó là số dư tính đến as_of_block. Khi bạn cần con số hiện tại của chuỗi, hãy đọc node_balance — nó được lấy từ một node TRON tại thời điểm yêu cầu và đối với TRX, theo công thức đầy đủ: số dư khả dụng cộng với frozenV2 đã stake cộng với số lượng đã ủy quyền đi. Trên một địa chỉ nắm giữ 41,7 triệu TRX đã stake, nó trả về 42035672.226020, con số này chính xác là 237799.226020 + 41760434 + 36816 + 623. Nếu chỉ đọc trường balance thông thường của node thì sẽ chỉ thấy 237 nghìn và sai lệch đến hai bậc độ lớn.

Nhưng node_balance không được điền cho mọi hàng. TRX và mọi TRC10 được trả về trong một lệnh gọi getaccount, vì vậy chúng luôn có giá trị này. TRC20 thì không thể: một node không có cách nào liệt kê các token TRC20 mà một địa chỉ nắm giữ, do đó balanceOf chỉ được truy vấn đối với các token lớn. Khi đo lường trên một ví có 504 hàng TRC20, 494 hàng trong số đó trả về null. Giá trị null đó là theo chính sách chứ không phải là lỗi, và giá trị null tương tự cũng xuất hiện nếu node tạm thời không thể truy cập được. Vì vậy đối với TRX và TRC10, giá trị hiện tại của chuỗi luôn sẵn có cho bạn; còn đối với TRC20 ít phổ biến, tất cả những gì bạn có là balance và block mà nó dựa trên.

Sổ cái chỉ tiến đến một block khi mọi tiến trình ghi chỉ mục đã xác nhận block đó, và mốc xác nhận (watermark) của nó là giá trị nhỏ nhất trong số tất cả các tiến trình đó. Các tiến trình ghi chậm nhất công bố mốc của chúng theo từng đợt, vì vậy khoảng cách giãn ra đều đặn rồi sau đó co lại nhanh chóng — dạng răng cưa, chứ không phải một hằng số.

Được lấy mẫu qua khoảng thời gian 20 phút vào ngày 6 tháng 9 năm 2026:

	Số block chậm hơn block đầu chuỗi	Thời gian chậm hơn
Tốt nhất	22	~1 phút
Trung vị	44	~2 phút
Phân vị thứ 90	86	~4 phút
Kém nhất từng ghi nhận	121	~6 phút

Hãy dự trù việc sổ cái chậm hơn chuỗi vài phút, chứ không phải vài giây.

Những hệ quả rút ra từ điều đó:

• Một địa chỉ không hoạt động sẽ chính xác ngay cả đối với thời điểm "hiện tại". Khi không có biến động nào diễn ra lâu hơn độ trễ hiện tại, sổ cái đã bắt kịp và balance bằng với node_balance.
• Trên một địa chỉ vừa mới giao dịch, balance có thể bị sai theo cả hai hướng — quá thấp khi một giao dịch chuyển tiền đến vẫn chưa được lập chỉ mục, quá cao khi một giao dịch chuyển tiền đi chưa được lập chỉ mục.
• live=true thu hẹp khoảng cách nhưng không xóa bỏ hoàn toàn. Nó áp dụng phần đuôi của các sự kiện chuyển tiền giữa as_of_block và block đầu chuỗi một cách tức thời, trong khoảng 30–80 ms. Nó không làm thay đổi as_of_block, không tính đến phí, và chủ đích bỏ qua các token TRC10 vốn được theo dõi bởi một chỉ mục riêng biệt. Một ví dụ đo lường thực tế: một địa chỉ có sổ cái báo cáo 157.317444 TRX đã trả về 766.194807 khi dùng live=true, trong khi node thực tế nắm giữ 1698.995472. Rất hữu ích, nhưng node_balance vẫn là trường duy nhất phản ánh giá trị hiện tại của chuỗi.
• Các câu trả lời lịch sử là chính xác tuyệt đối. /at, /at-block, /history, /summary và /statement mô tả các thời điểm mà sổ cái đã vượt qua từ lâu. Không có độ trễ nào cần phải tính đến.

Đối với kế toán, đối soát và báo cáo sao kê, hãy sử dụng các endpoint lịch sử và hoàn toàn tin cậy chúng. Đối với màn hình ví theo thời gian thực, hãy hiển thị node_balance ở những nơi nó xuất hiện — bao gồm TRX và mọi TRC10 — và dự phòng về balance kèm theo as_of_block bên cạnh ở những nơi có giá trị null, để người đọc biết con số đó thuộc về block nào.

/history chỉ trả về những ngày có hoạt động. Yêu cầu days=7 trên một địa chỉ chỉ có giao dịch trong ba ngày sẽ trả về ba điểm dữ liệu, không phải bảy. Mỗi điểm mang balance đóng của ngày hôm đó và delta so với điểm trước đó.

/summary tự cân đối số liệu. Đối với mọi token opening_balance + period_in − period_out − period_fees = closing_balance, và hệ thống trả về phép tính số học đó được viết sẵn trong control_formula, ví dụ 76493.940406 + 141490.950160 - 216763.731366 - 79.260200 = 1141.899000. Phí được tách riêng thành period_fees_energy và period_fees_bandwidth. Lưu ý rằng /summary có thể báo cáo một số dư âm nhỏ cho một token mà endpoint số dư hiện tại bỏ qua hoàn toàn.

/statement bị giới hạn bởi ops_limit. Nó chấp nhận từ 10 đến 5000 hoạt động; bất kỳ giá trị nào ngoài phạm vi đó đều trả về 422. operations_total là số lượng thực tế trong khoảng thời gian và operations_truncated cho biết liệu danh sách có bị cắt bớt hay không. token_id mặc định là TRX khi bị bỏ trống. Để có bản sao kê đầy đủ vượt quá 5000 hoạt động, hãy yêu cầu một tệp thay thế — xem Tệp sao kê.

Thứ tự token được sắp xếp có chủ đích. TRX và các stablecoin lớn đứng đầu, tiếp theo là các token đã xác minh có giá, sau đó là mọi thứ khác. Không sắp xếp lại theo số lượng: các đợt airdrop rác thường mang số dư danh nghĩa khổng lồ và sẽ bị đẩy lên trên cùng.

Thư rác được đánh dấu chứ không bị xóa. is_spam gắn cờ các token được phân loại là lừa đảo. Truyền hide_spam=true để loại bỏ chúng khỏi phản hồi; TRX và USDT không bao giờ bị ẩn.

Giới hạn tốc độ

Mỗi endpoint chấp nhận 10 yêu cầu mỗi giây, được chia sẻ giữa tất cả các client của endpoint đó. Giới hạn tính trên từng endpoint, vì vậy /history và /summary không cạnh tranh lẫn nhau.

Vượt quá giới hạn sẽ nhận 429 kèm theo Retry-After: 1, cùng với RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset. Thử lại sau khoảng thời gian trì hoãn đã nêu.

Một giới hạn thứ hai rộng hơn nhiều là 100 yêu cầu mỗi giây trên mỗi IP nguồn áp dụng trên toàn bộ API. Hai giới hạn này được phân biệt bằng thông báo: giới hạn endpoint thông báo Endpoint rate limit exceeded (10 req/s shared), giới hạn trên toàn tài khoản thông báo API rate limit exceeded.

Lỗi

HTTP	Ý nghĩa
400	địa chỉ có 34 ký tự nhưng không vượt qua kiểm tra tổng kiểm (checksum) base58
401	khóa bị thiếu hoặc không hợp lệ, hoặc IP nguồn không nằm trong danh sách trắng
402	số dư tài khoản dưới mức tối thiểu 4 TRX
403	khóa API bị khóa; liên hệ hỗ trợ
422	một tham số bị thiếu hoặc nằm ngoài phạm vi — độ dài địa chỉ sai, hoặc ops_limit ngoài khoảng 10–5000
429	vượt quá giới hạn tốc độ
503	hệ thống số dư không phản hồi; yêu cầu không bị tính lượt, hãy thử lại

Phần thân lỗi có ba định dạng, tùy thuộc vào tầng nào đã từ chối yêu cầu. Hãy khớp theo trạng thái HTTP, không khớp theo phần thân phản hồi.

// 401, 402, 403 — cổng API, trước khi yêu cầu đến được dịch vụ
{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}

// 400, 422 — dịch vụ, sau khi các tham số được phân tích
{"status": "error", "code": -4, "msg": "address must be base58 (T...)", "data": {"code": -4, "msg": "address must be base58 (T...)"}}

// 429 — bộ giới hạn tốc độ
{"message": "Endpoint rate limit exceeded (10 req/s shared), retry shortly", "request_id": "e5dbf25437d2eb215c764617d50b8d3b"}

Liên quan

• Tệp sao kê — bản sao kê đầy đủ dưới dạng tệp CSV hoặc PDF
• Webhook báo cáo — nhận thông báo khi một tệp đã sẵn sàng