Consulta TRC-20 Saldo de tokens a través de API en TRON

La lectura de saldos de TRC-20 es la base de los paneles de pago, las integraciones de intercambio y las aplicaciones de billetera en TRON. A diferencia de TRX (nativo), los saldos de tokens se encuentran dentro del contrato inteligente de cada token: usted consulta balanceOf(address) en el contrato.

Esta guía muestra TronWeb, TronGrid REST y consideraciones de producción para USDT y tokens TRC-20 arbitrarios.

USDT referencia del contrato

Oficial de Mainnet USDT:

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Decimales: 6 (1 USDT = 1_000_000 unidades base).

Método 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;
}

Nota: el comportamiento .call() puede devolver objetos similares a BigNumber; normalícelo cuidadosamente en producción.

Método 2: punto final de la cuenta TronGrid

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

La respuesta incluye una matriz trc20 con saldos de tokens codificados por dirección de contrato.

Ejemplo de análisis (la estructura puede variar):

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;
}

Bueno para enumerar todos los tokens a la vez; menos preciso para casos extremos de pagos en tiempo real.

Método 3: desencadenar contrato constante

HTTP de bajo nivel por activador de contrato inteligente:

• function_selector: balanceOf(address)
• parameter: dirección del titular codificada en ABI
• contract_address: contrato simbólico

Úselo cuando TronWeb no esté disponible (pilas que no sean JS).

Manejo de decimales

Nunca asumas 18 decimales. Llame siempre a decimals() o utilice constantes conocidas:

Utilice matemáticas de números enteros (BigInt) para obtener precisión financiera: evite errores flotantes de JavaScript en saldos grandes.

TRX saldo junto con tokens

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

Los usuarios necesitan TRX para las tarifas incluso cuando solo tienen USDT.

Patrones de producción {#producción}

Encuesta de pago

Para aceptar pagos USDT:

1. Genere una dirección de depósito única por usuario o realice un seguimiento por monto + patrón de nota
2. Encuesta balanceOf después del plazo de pago previsto
3. Mejor: oyentes de eventos en eventos USDT Transfer

Almacenamiento en caché

• Saldos de caché con TTL corto (10 a 30 s) para la interfaz de usuario
• Invalidar en caso de evento entrante Transfer detectado

Límites de tarifas

Respete los límites TronGrid: consultas de direcciones por lotes fuera de las horas pico.

Compatibilidad con múltiples tokens

Ayudante abstracto:

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) };
}

Consultas de saldo por lotes

Para muchas direcciones, evite llamadas constantes N+1. Utilice el punto final de tokens de cuenta TronGrid v1 o realice una paralelización con el conocimiento del límite de velocidad. Indexe las direcciones de depósito en su base de datos y sondee solo las facturas activas para reducir la carga de API.

Errores en el manejo de decimales

USDT utiliza 6 decimales; muchos tokens TRC-20 usan 18. Nunca muestre balanceOf sin formato sin dividir por 10**decimals. Almacene cantidades como cadenas o BigInt en JavaScript para evitar errores de punto flotante. Los errores de un decimal han provocado que los sistemas de pago acrediten entre 1 y 12 veces el monto previsto en incidentes de producción en otras cadenas; el mismo riesgo se aplica en TRON.

Lista de verificación para solucionar problemas

Si algo sale mal en TRON, trátelo como un problema de depuración estructurado: confirme el txid exacto en la cadena, verifique la dirección del contrato de destino y solo entonces decida si la falla es recuperable. En TRON, muchos problemas "misteriosos" son simplemente uno de: red incorrecta (mainnet vs testnet), contrato de token incorrecto (falso USDT/tokens con nombres similares), recursos insuficientes (OUT_OF_ENERGY/ancho de banda) o retraso en la interfaz de usuario/indexador entre la billetera y el explorador.

Comience con estas comprobaciones en cadena:

• Copie siempre el txid/hash completo de su billetera o explorador.
• Confirme el estado del resultado del tx en TronScan (SUCCESS, REVERT, OUT_OF_ENERGY o aún pendiente).
• Compruebe si la dirección del destinatario/contrato coincide con la que desea enviar.
• Si se trata de una llamada de contrato, confirme que el selector de función y los parámetros coincidan con el estándar de token que cree que está utilizando (TRC-20 vs TRC-10 vs BEP-20 en BSC).

Luego aplique la ruta de corrección para su categoría:

• Confirmar el estado y los parámetros de la transacción.
• Verificar direcciones (contrato de token, destinatario, enrutador/gastador).
• Agregar o delegar recursos (Energía/Ancho de banda) cuando el fallo esté basado en recursos.

Errores comunes

Estos patrones causan la mayoría de los errores a nivel de usuario:

• Usar direcciones de mainnet en testnet (o al revés).
• Copiar un símbolo de token en lugar de la dirección del contrato TRC-20 real.
• Firmar la dirección de aprobación/gastador incorrecta porque el enlace de la interfaz de usuario es malicioso o está desactualizado.
• Reintentar sin cambiar la entrada fallida (por ejemplo, REVERT sigue revirtiéndose hasta que corrija el parámetro).

Si no está seguro, no “simplemente envíe de nuevo”. Realice un cambio controlado, verifique en TronScan y luego continúe.

Preguntas frecuentes

¿Cómo sé si una transacción está realmente confirmada?Utilice TronScan y verifique el estado del resultado del tx. Las etiquetas "pendientes" de la billetera pueden retrasarse; El estado de la cadena es la fuente de la verdad. Copie txid y verifique SUCCESS/REVERT/OUT_OF_ENERGY, no solo el texto de la interfaz de usuario.

¿Por qué la interfaz de usuario difiere de TronScan?

Algunas billeteras y dApps utilizan diferentes indexadores o capas de caché. Es normal que haya un breve retraso entre la transmisión y la indexación; compare txid y espere a que la cadena se estabilice antes de concluir que hay una falla.

¿Qué debo hacer después de un REVERT?

Detenga y decodifique la llamada fallida. La mayoría de los REVERT se deben a parámetros no válidos, dirección de contrato incorrecta, aprobaciones faltantes o una falta de coincidencia entre el estándar del token y el método. Solucione la causa y luego vuelva a firmar.

¿Es seguro firmar una aprobación ilimitada?

Las aprobaciones ilimitadas son seguras solo para direcciones de gastadores confiables que usted haya verificado (fuente verificada, enrutador correcto y contrato de token esperado). Para las pruebas, prefiera aprobaciones limitadas y revoque una vez que haya terminado.

¿Qué recursos requiere TRON para las llamadas de contrato?

La ejecución de contratos inteligentes consume principalmente energía, mientras que los bytes de transacciones consumen ancho de banda. Si recibe OUT_OF_ENERGY, agregue/congela/delegue energía. Si se agota el ancho de banda, concéntrese en mantener suficiente líquido TRX para bytes y asignación de recursos.

¿Cómo puedo reducir los tickets de soporte?

Muestre a los usuarios un mensaje claro de "qué sucedió" basado en el estado de la cadena y vincule directamente a la guía relevante (pendiente, fallida, sin energía o verificación). Guarda txid para que puedas conciliar rápidamente.

Guías relacionadas

• Aceptar API de pagos USDT
• TronGrid Guía API
• Enviar USDT programáticamente
• TRON Referencia de API HTTP

Preguntas frecuentes

¿Cuál es la dirección del contrato USDT en la red principal TRON?

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: verifique siempre en TronScan antes del uso en producción.

¿BalanceOf requiere una clave privada?

No. balanceOf es una llamada de contrato de solo lectura que cualquier nodo completo o TronGrid puede ejecutar.

¿Por qué el saldo API difiere del TronLink?

Horario, txs no confirmados o dirección de contrato incorrecta. Confirme el último bloque y contrato.

¿Puedo consultar el saldo histórico?

Requiere un nodo de archivo/indexador, no un punto final de cuenta estándar TronGrid. Utilice la API TronScan o indexe los eventos Transfer usted mismo.

¿Qué tan rápido se actualiza el saldo después de la transferencia?

Después de que se confirme la transacción (~3s). Encuesta getTransaction hasta SUCCESS y luego lee el saldo.