TRON API: pagos USDT-TRC20 vía REST

Tether había emitido unos 190 mil millones de dólares de USDT hacia abril de 2026. TRON llevaba aproximadamente el 45% de ese suministro, unos 85 mil millones de dólares, con Ethereum cerca detrás con alrededor del 40%; ambas chains se han intercambiado el liderazgo más de una vez desde finales de 2025. En la propia TRON, el panorama es inequívoco: USDT representó el 98,6% del valor en stablecoins de la chain en el primer trimestre de 2026. Quien diga TRC-20, en la práctica está diciendo USDT.

El suministro es solo la mitad de la historia. El volumen de transferencias te dice para qué se usa una chain, y el volumen de USDT de TRON se acercó a los 2 billones de dólares en el primer trimestre de 2026. El USDT de Ethereum tiende hacia el colateral de DeFi y la liquidación institucional. El de TRON es la versión que la gente realmente mueve: depósitos de exchange, remesas, pagos a contratistas en países donde un saldo en dólares supera a la cuenta bancaria local.

Para una decisión de integración, la consecuencia es clara. Si tus usuarios eligen una red de depósito en un desplegable, TRC-20 será la opción más elegida, y los tickets de soporte por red equivocada bajan cuando tu opción por defecto coincide con lo que los usuarios esperan. Construye TRON primero; el esquema de solicitud compartido te permite añadir las demás chains después sin código nuevo.

TRON mide dos recursos. Bandwidth cubre las transferencias simples y es gratis hasta 600 puntos al día. Energy no tiene asignación gratuita y se aplica siempre que se ejecuta un smart contract, razón por la cual una transferencia de USDT, una llamada a contrato TRC-20, siempre cuesta más que enviar TRX simple.

TRON no tiene un único precio de gas. La red mide dos recursos separados, y saber cuál consume tu transacción es la diferencia entre comisiones predecibles y tickets de soporte sorpresa.

Bandwidth se cobra en cada transacción y sigue el tamaño en bytes. Cada cuenta recibe 600 puntos gratis al día; una transferencia simple de TRX pesa entre 250 y 300 bytes, así que las transferencias ocasionales de TRX no cuestan nada en absoluto. Superada la cuota gratuita, la red quema 0,001 TRX por punto, aproximadamente 0,35 TRX para una transferencia TRC-20 típica.

Energy solo se aplica cuando se ejecuta un smart contract, y no tiene asignación diaria gratuita. Una transferencia de USDT es una llamada a contrato, el contrato TRC-20 actualiza su tabla interna de saldos, así que necesita Energy además de Bandwidth. Desde que la Proposal #104 de gobernanza entró en vigor en agosto de 2025, una unidad de Energy cuesta 100 Sun, la mitad de los 210 anteriores. Una transferencia a una dirección que ya tiene USDT consume unas 64.000 unidades de Energy, lo que equivale a 6,4 TRX. Una transferencia a una dirección que nunca ha tenido USDT escribe una entrada de almacenamiento nueva, y el estado nuevo cuesta aproximadamente el doble de Energy que una actualización: unas 134.000 unidades, o 13,4 TRX.

Antes de enviar, dos herramientas concretan las cifras. La calculadora de comisiones de TRON calcula Bandwidth, Energy y el total en TRX para una transacción concreta, y GET /api/v2/tron/chainparameters devuelve los precios unitarios en vivo para que tu código nunca fije una constante que la siguiente votación de gobernanza cambie. La guía de comisiones cubre la mecánica en profundidad.

Cada transferencia TRC-20 necesita Energy, y esa Energy tiene que venir de algún sitio. Para la mayoría de remitentes, la fuente es su propio saldo de TRX. Ese supuesto se rompe en dos situaciones habituales, y ambas generan dolor operativo hasta que las resuelves de forma estructural.

Tu propia flota de wallets de depósito

Cada wallet que reenvía fondos a una hot wallet necesita su propio saldo de TRX para la consolidación, y con unos pocos miles de wallets, mantenerlas cargadas se convierte en un trabajo en sí mismo, con su propio coste de comisión para las transferencias de recarga. Las comisiones patrocinadas eliminan ese trabajo. La forma recomendada de configurar esto hoy es TronFuel, que alquila Energy obtenida a granel de los stakers — el mismo mecanismo que la guía de comisiones describe como capaz de recortar los costes de comisión hasta un 60% frente a quemar TRX al precio de mercado. Los endpoints de Paymaster heredados de Chaingateway hacen lo mismo y siguen disponibles para integraciones existentes.

Tus clientes finales

Un usuario tiene 200 USDT en una wallet de autocustodia y cero TRX; el USDT llegó de un exchange o de otra persona, y nadie le dijo que se necesita una segunda moneda para moverlo. Cuando intenta pagarte o retirar, la transferencia falla. Desde la perspectiva del usuario, el dinero está atascado. Desde la perspectiva de tu cola de soporte, es un ticket recurrente que ninguna entrada de FAQ mata del todo, porque la solución, "ve a comprar algo de TRX en un exchange primero", es exactamente la fricción que el cliente quería evitar usando stablecoins. Una transferencia patrocinada acaba con esto: envías la transferencia, el patrocinador cubre Energy y Bandwidth, el coste recae en tu cuenta, y el cliente nunca aprende qué es TRX. Para flujos de checkout y retiro, este único cambio elimina el modo de fallo más común de los pagos TRC-20.

Poner precio y crear una transferencia patrocinada

Primero calcula el precio de una transacción patrocinada, luego créala:

# 1. Estima la comisión
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500"}'

# 2. Crea la solicitud de Paymaster
curl -X POST https://app.chaingateway.io/api/v2/tron/paymaster \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TDepositWallet", "to": "THotWallet", "amount": "500", "password": "YourWalletPassword"}'

GET /api/v2/tron/paymaster lista cada solicitud que has creado e informa de su estado, desde pendiente hasta completada o fallida, y GET /api/v2/tron/paymaster/balance muestra el crédito de patrocinio que te queda — juntos cubren la conciliación.

Importar una private key es el camino más rápido a producción, pero algunos equipos no pueden enviar material de key a un tercero en absoluto. La razón puede ser una política interna, un regulador, o un módulo de seguridad de hardware cuyas keys físicamente no se pueden exportar. La TRON API tiene un segundo modo construido exactamente para esta restricción.

El flujo tiene tres pasos. Llama a POST /api/v2/tron/transactions/trc20/build, o a /api/v2/tron/transactions/build para TRX simple, con los mismos campos que usarías para un envío normal. La API devuelve la transacción en bruto sin firmar. Firma ese payload donde vivan tus keys: un HSM, una máquina aislada, un servicio de firma detrás de tu propio firewall. Luego envía el resultado firmado mediante POST /api/v2/tron/transactions/broadcast, que lo transmite a la red y devuelve el hash de la transacción.

# 1. Construye la transacción sin firmar
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20/build \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "from": "TColdWallet", "to": "TRecipient", "amount": 1000}'

# 2. Firma localmente con tu propia herramienta, luego transmite
curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signed_transaction": "<the signed transaction as a JSON string>"}'

Dos cosas que conviene saber antes de elegir este modo. Una transacción de TRON construida caduca tras una ventana corta, así que el paso de firmar y transmitir debe ocurrir con prontitud en lugar de quedarse en una cola durante toda la noche. Y la responsabilidad operativa cambia de lado: tú te encargas de la librería de firma y sus actualizaciones. Lo que ganas es que Chaingateway nunca ve un secreto. La monitorización de depósitos no se ve afectada de ningún modo, ya que observar una dirección no requiere ninguna key. Muchas configuraciones de producción mezclan ambos modos, keys importadas para wallets operativas de bajo valor, auto-firma para la ruta de tesorería.

Hacer polling a un explorador en busca de transferencias entrantes desperdicia solicitudes y aun así falla en el momento exacto. Chaingateway envía en su lugar. Registra un webhook y tu backend recibe un POST con el estado de la transacción, las confirmaciones y los cambios de saldo. Fija un secreto personal en tu cuenta y cada entrega lleva una cabecera X-Signature — un HMAC-SHA256 en base64 del txid del payload — para que puedas verificar al remitente. Las entregas que fallan quedan en una lista de notificaciones fallidas, y POST /api/v2/tron/webhooks/notifications/{id}/retry reenvía cualquiera de ellas.

GET /api/v2/tron/webhooks/notifications devuelve las notificaciones pasadas, útil cuando necesitas reproducir eventos tras un despliegue defectuoso. La configuración lleva unos minutos con la guía de webhooks.

Los remitentes de alto volumen no deberían quemar TRX para siempre. Haz freeze de TRX mediante POST /api/v2/tron/freeze y la red concede Bandwidth o Energy a cambio; enruta esos recursos a tu hot wallet con POST /api/v2/tron/delegate. Unfreeze y undelegate revierten ambos pasos cuando quieras recuperar el capital.

Los precios actuales de recursos vienen de GET /api/v2/tron/chainparameters. Desde la Proposal #104, el precio unitario de Energy es de 100 Sun, frente a los 210 anteriores, lo cual cambió el punto de equilibrio entre hacer staking y quemar. Comprueba el valor en vivo antes de dimensionar un staking.

La aritmética favorece el staking a medida que crece el volumen, porque el TRX quemado desaparece mientras que el TRX en staking solo está aparcado. Como cifra aproximada de mediados de 2026, un staking del orden de 5.000 TRX generaba aproximadamente el equivalente en Energy a una transferencia de USDT al día. Un negocio que envía 50 transferencias al día necesitaría un staking del orden de cientos de miles de TRX para cubrir toda su Energy solo con staking. Trata estas cifras como órdenes de magnitud y no como cotizaciones: tu rendimiento diario depende de cuánto TRX tenga en staking toda la red, y esa proporción varía. La calculadora de comisiones y el endpoint de parámetros de la chain te dan las entradas de hoy para el cálculo.

La delegación es lo que hace que el staking sea operativamente limpio. Mantén el staking en una dirección de tesorería que nunca toque el tráfico de clientes, y luego haz delegate de su Energy hacia las hot wallets que realizan los envíos reales. Cuando una wallet se retira, haz undelegate y apunta los recursos a su sucesora; el TRX en staking en sí nunca se mueve. Una advertencia para la planificación de tesorería: tras hacer unfreeze, el TRX permanece bloqueado durante un período de espera de alrededor de dos semanas antes de poder gastarse de nuevo, así que un staking no es una reserva de acceso instantáneo. Dimensiónalo según el volumen en estado estable y cubre los picos con Energy alquilada.

Chaingateway admite los tipos de token estándar en TRON. USDT, USDC y DAI funcionan de fábrica con manejo automático de decimales. Para un token que hayas lanzado tú mismo, pasa su contract address y la API lo trata como cualquier otro TRC-20. El esquema de solicitud se comparte entre chains, así que la llamada ERC-20 en Ethereum, BNB Smart Chain, Polygon o Arbitrum se ve exactamente como tu llamada TRC-20, con un segmento de ruta distinto.

La red está diseñada para unas 2.000 transacciones por segundo, lo cual encaja con cargas de pago compuestas por muchas transferencias pequeñas. Las comisiones se mantienen lo bastante bajas como para que los micropagos sigan siendo viables, unos pocos TRX por transferencia de token en lugar de una comisión que se come el pago. TRON tiene una cuota mayor del USDT en circulación que cualquier otra chain, así que las contrapartes con las que tratan tus usuarios ya están ahí, y el ecosistema de wallets en torno a TRC-20 está lo bastante maduro como para que las herramientas rara vez estorben.

Las integraciones típicas se ven así: un flujo de checkout que acepta USDT y acredita el pedido tras la confirmación; un backend de exchange que observa miles de direcciones de depósito y procesa retiros desde una hot wallet; sistemas de pago que ejecutan airdrops o calendarios de vesting; facturación de suscripciones que cobra en stablecoins cada mes; servicios de remesas que mueven valor a través de fronteras en minutos. La misma API cubre cada patrón. Lo que cambia es qué endpoints combinas.

Cada endpoint de esta página acepta la cabecera X-Network: testnet. Con ella, la misma solicitud se ejecuta contra la testnet de TRON: mismas rutas, mismos payloads, mismas formas de respuesta. El TRX de prueba sale gratis de faucets públicos, así que un ensayo completo no cuesta nada — crea una dirección de depósito, envíale una transferencia TRC-20, recibe el webhook, verifica la firma HMAC, consolida a una hot wallet.

Ensaya la ruta del webhook al menos una vez de principio a fin. Los errores clásicos de integración, una comprobación de firma contra la codificación de payload equivocada o un firewall que descarta la entrega en silencio, salen a la luz en testnet exactamente igual que lo harían en producción, donde cuestan depósitos reales en lugar de tokens de prueba. Salir a producción después significa borrar una cabecera; el quickstart muestra el ciclo completo.

Dos clases de fallo quieren un manejo opuesto. Una respuesta 4xx significa que la solicitud en sí está mal: un Bearer token ausente o caducado, una dirección malformada, un importe que la wallet emisora no puede cubrir. Regístralo y corrige la causa, pero no reintentes sin cambios, porque una entrada idéntica produce un rechazo idéntico. Una respuesta 5xx o un timeout de red no dicen nada sobre tu entrada; reintenta esos con backoff exponencial y un tope.

El caso límite que merece diseño propio es el timeout tras un envío. Tu cliente HTTP se rindió, pero la transacción puede haberse transmitido de todas formas. Enviar la misma transferencia otra vez por reflejo es cómo suceden los pagos duplicados. Comprueba primero qué salió realmente: GET /api/v2/tron/transactions lista las transferencias creadas a través de tu cuenta. Reenvía solo si el primer intento falló de forma verificable. Para fallos relacionados con la comisión hay un patrón aún más barato: comprueba GET /api/v2/tron/chainparameters y los recursos de la wallet antes de enviar, convirtiendo un error en tiempo de ejecución en una comprobación previa.