Truy vấn TRC-20 Số dư mã thông báo qua API trên TRON

Dành cho dev · Cập nhật 8 thg 7, 2026 · 10 phút đọc

Đọc số dư TRC-20 là nền tảng cho bảng điều khiển thanh toán, tích hợp trao đổi và ứng dụng ví trên TRON. Không giống như TRX (bản địa), số dư mã thông báo nằm trong hợp đồng thông minh của mỗi mã thông báo — bạn truy vấn balanceOf(address) trên hợp đồng.

Hướng dẫn này trình bày TronWeb, TronGrid REST và các cân nhắc về sản xuất cho USDT và mã thông báo TRC-20 tùy ý.

USDT tham chiếu hợp đồng

Mainnet chính thức USDT:

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Số thập phân: 6 (1 USDT = 1_000_000 đơn vị cơ bản).

Cách 1: TronWeb

const TronWeb = require('tronweb');

const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY },
});

const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';

async function getTrc20Balance(holderAddress, contractAddress = USDT) {
  if (!tronWeb.isAddress(holderAddress)) throw new Error('Invalid address');
  const contract = await tronWeb.contract().at(contractAddress);
  const raw = await contract.balanceOf(holderAddress).call();
  const decimals = await contract.decimals().call();
  const divisor = Math.pow(10, Number(decimals));
  return Number(raw) / divisor;
}

Lưu ý: Hành vi .call() có thể trả về các đối tượng giống BigNumber - chuẩn hóa cẩn thận trong quá trình sản xuất.

Cách 2: TronGrid điểm cuối tài khoản

GET https://api.trongrid.io/v1/accounts/{address}

Phản hồi bao gồm mảng trc20 với số dư mã thông báo được khóa theo địa chỉ hợp đồng.

Phân tích ví dụ (cấu trúc có thể thay đổi):

async function getUsdtFromAccountApi(address) {
  const res = await fetch(
    `https://api.trongrid.io/v1/accounts/${address}`,
    { headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY } }
  );
  const json = await res.json();
  const trc20 = json.data?.[0]?.trc20 || [];
  for (const entry of trc20) {
    const [[contract, balance]] = Object.entries(entry);
    if (contract === USDT) return Number(balance) / 1e6;
  }
  return 0;
}

Tốt cho việc liệt kê tất cả mã thông báo cùng một lúc; kém chính xác hơn đối với các trường hợp thanh toán theo thời gian thực.

Cách 3: triggerconstantcontract

HTTP cấp thấp cho mỗi hợp đồng thông minh kích hoạt:

function_selector: balanceOf(address)
parameter: Địa chỉ chủ sở hữu được mã hóa ABI
contract_address: hợp đồng token

Sử dụng khi TronWeb không có sẵn (ngăn xếp không phải JS).

Xử lý số thập phân

Không bao giờ giả sử 18 số thập phân. Luôn gọi decimals() hoặc sử dụng các hằng số đã biết:

Mã thông báo	Số thập phân
USDT	6
Nhiều mã thông báo tùy chỉnh	18

Sử dụng phép toán số nguyên (BigInt) để có độ chính xác về mặt tài chính — tránh lỗi thả nổi JavaScript trên số dư lớn.

Số dư ## TRX cùng với token {#trx}

const balanceSun = await tronWeb.trx.getBalance(address);
const balanceTrx = tronWeb.fromSun(balanceSun);

Người dùng cần TRX để trả phí ngay cả khi chỉ giữ USDT.

Mô hình sản xuất

Thăm dò thanh toán

Đối với chấp nhận thanh toán USDT:

Tạo địa chỉ gửi tiền duy nhất cho mỗi người dùng hoặc theo dõi theo số tiền + mẫu ghi nhớ
Thăm dò ý kiến balanceOf sau thời hạn thanh toán dự kiến
Tốt hơn: người nghe sự kiện trên sự kiện USDT Transfer

Bộ nhớ đệm

Cân bằng bộ đệm với TTL ngắn (10–30 giây) cho giao diện người dùng
Không hợp lệ khi phát hiện sự kiện Transfer đến

Giới hạn tỷ lệ

Tôn trọng TronGrid giới hạn — truy vấn địa chỉ hàng loạt ngoài giờ cao điểm.

Hỗ trợ nhiều token

Người trợ giúp trừu tượng:

async function getTokenBalance(holder, tokenContract) {
  const c = await tronWeb.contract().at(tokenContract);
  const [raw, decimals] = await Promise.all([
    c.balanceOf(holder).call(),
    c.decimals().call(),
  ]);
  return { raw: raw.toString(), decimals: Number(decimals) };
}

Truy vấn số dư hàng loạt

Đối với nhiều địa chỉ, tránh các cuộc gọi liên tục N+1. Sử dụng điểm cuối mã thông báo tài khoản TronGrid v1 hoặc song song với nhận thức về giới hạn tỷ lệ. Lập chỉ mục các địa chỉ gửi tiền trong cơ sở dữ liệu của bạn và chỉ thăm dò các hóa đơn đang hoạt động để giảm tải API.

Cạm bẫy xử lý số thập phân

USDT sử dụng 6 số thập phân; nhiều mã thông báo TRC-20 sử dụng 18. Không bao giờ hiển thị balanceOf thô mà không chia cho 10**decimals. Lưu trữ số lượng dưới dạng chuỗi hoặc BigInt trong JavaScript để tránh lỗi dấu phẩy động. Các lỗi sai số thập phân đã khiến hệ thống thanh toán ghi có gấp 1e12 lần số tiền dự kiến trong các sự cố sản xuất trên các chuỗi khác - rủi ro tương tự cũng áp dụng trên TRON.

Danh sách kiểm tra khắc phục sự cố

Nếu có sự cố xảy ra trên TRON, hãy xử lý nó như một vấn đề gỡ lỗi có cấu trúc: xác nhận txid chính xác trên chuỗi, xác minh địa chỉ hợp đồng mục tiêu và chỉ sau đó mới quyết định xem liệu lỗi có thể phục hồi được hay không. Trên TRON, nhiều vấn đề “bí ẩn” chỉ đơn giản là một trong số: mạng sai (mainnet so với testnet), hợp đồng mã thông báo sai (USDT giả / mã thông báo có tên tương tự), không đủ tài nguyên (OUT_OF_ENERGY / băng thông) hoặc độ trễ giao diện người dùng/trình lập chỉ mục giữa ví và trình thám hiểm.

Bắt đầu với các bước kiểm tra dựa trên chuỗi sau:

Luôn sao chép toàn bộ txid/hash từ ví hoặc explorer của bạn.
Xác nhận trạng thái kết quả tx trên TronScan (SUCCESS, REVERT, OUT_OF_ENERGY hoặc vẫn đang chờ xử lý).
Kiểm tra xem địa chỉ người nhận/hợp đồng có khớp với nội dung bạn định gửi hay không.
Nếu đó là lệnh gọi hợp đồng, hãy xác nhận rằng bộ chọn chức năng và các tham số phù hợp với tiêu chuẩn mã thông báo mà bạn cho rằng mình đang sử dụng (TRC-20 so với TRC-10 so với BEP-20 trên BSC).

Sau đó áp dụng đường dẫn sửa lỗi cho danh mục của bạn:

Xác nhận trạng thái và thông số giao dịch.
Xác minh địa chỉ (hợp đồng mã thông báo, người nhận, bộ định tuyến/người chi tiêu).
Thêm hoặc ủy quyền tài nguyên (Năng lượng/Băng thông) khi lỗi do tài nguyên.

###Những lỗi thường gặp

Các mẫu này gây ra hầu hết các lỗi ở cấp độ người dùng:

Sử dụng địa chỉ mainnet trên testnet (hoặc ngược lại).
Sao chép ký hiệu mã thông báo thay vì địa chỉ hợp đồng TRC-20 thực tế.
Ký sai địa chỉ phê duyệt/chi tiêu do liên kết UI độc hại hoặc lỗi thời.
Thử lại mà không thay đổi đầu vào bị lỗi (ví dụ: REVERT tiếp tục hoàn nguyên cho đến khi bạn sửa được tham số).

Nếu bạn không chắc chắn, đừng “gửi lại”. Thực hiện một thay đổi có kiểm soát, xác minh trên TronScan rồi tiếp tục.

##Câu hỏi thường gặp

Làm cách nào để biết liệu giao dịch có thực sự được xác nhận hay không?Sử dụng TronScan và kiểm tra trạng thái kết quả tx. Nhãn “đang chờ xử lý” của ví có thể bị trễ; trạng thái dây chuyền là nguồn gốc của sự thật. Sao chép txid và xác minh SUCCESS/REVERT/OUT_OF_ENERGY, không chỉ văn bản giao diện người dùng.

Tại sao giao diện người dùng khác với TronScan?

Một số ví và dApp sử dụng các bộ chỉ mục hoặc lớp bộ đệm khác nhau. Độ trễ ngắn giữa phát sóng và lập chỉ mục là bình thường; so sánh txid và đợi chuỗi ổn định trước khi kết luận thất bại.

Tôi nên làm gì sau REVERT?

Dừng và giải mã cuộc gọi thất bại. Hầu hết REVERT đều do tham số không hợp lệ, địa chỉ hợp đồng sai, thiếu phê duyệt hoặc không khớp giữa tiêu chuẩn và phương thức mã thông báo. Khắc phục nguyên nhân rồi ký lại.

Ký phê duyệt không giới hạn có an toàn không?

Phê duyệt không giới hạn chỉ an toàn đối với các địa chỉ chi tiêu đáng tin cậy mà bạn đã xác minh (nguồn đã xác minh, bộ định tuyến chính xác và hợp đồng mã thông báo dự kiến). Để thử nghiệm, hãy ưu tiên phê duyệt có giới hạn và thu hồi sau khi bạn hoàn thành.

TRON yêu cầu những tài nguyên gì cho cuộc gọi hợp đồng?

Việc thực thi hợp đồng thông minh chủ yếu tiêu thụ Năng lượng, trong khi byte giao dịch tiêu thụ Băng thông. Nếu bạn nhận được OUT_OF_ENERGY, hãy thêm/đóng băng/ủy thác Năng lượng. Nếu băng thông cạn kiệt, hãy tập trung vào việc giữ đủ chất lỏng TRX để phân bổ byte và tài nguyên.

Làm cách nào để giảm phiếu hỗ trợ?

Hiển thị cho người dùng thông báo rõ ràng về “điều gì đã xảy ra” dựa trên trạng thái chuỗi và liên kết trực tiếp đến hướng dẫn có liên quan (đang chờ xử lý, không thành công, hết năng lượng hoặc xác minh). Lưu trữ txid để bạn có thể hòa giải nhanh chóng.

Hướng dẫn liên quan {#có liên quan}

Câu hỏi thường gặp

Địa chỉ hợp đồng USDT trên mạng chính TRON là gì?

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t — luôn xác minh trên TronScan trước khi sử dụng sản xuất.

BalanceOf có yêu cầu khóa riêng không?

Không. BalanceOf là lệnh gọi hợp đồng chỉ đọc mà bất kỳ nút đầy đủ hoặc TronGrid nào cũng có thể thực thi.

Tại sao số dư API khác với TronLink?

Thời gian, tin nhắn chưa được xác nhận hoặc địa chỉ hợp đồng sai. Xác nhận khối và hợp đồng mới nhất.

Tôi có thể truy vấn số dư lịch sử không?

Yêu cầu nút lưu trữ/bộ chỉ mục — không phải điểm cuối tài khoản TronGrid tiêu chuẩn. Hãy tự mình sử dụng API TronScan hoặc lập chỉ mục các sự kiện Transfer.

Số dư được cập nhật sau khi chuyển khoản nhanh như thế nào?

Sau khi giao dịch được xác nhận (~3s). Thăm dò getTransaction cho đến SUCCESS rồi đọc số dư.

Hướng dẫn này có hữu ích không?

Cảm ơn phản hồi của bạn — giúp chúng tôi cải thiện tài liệu.