API de direcciones TRC20: genera direcciones y vigílalas para detectar depósitos
Una dirección TRC20 es una dirección de cuenta estándar de TRON: 34 caracteres en forma Base58Check, que empieza por T. Guarda TRX y todos los tokens TRC-20, como USDT. La misma dirección tiene una grafía hexadecimal de 42 caracteres que empieza por 41. Enviar desde ella cuesta Energy y Bandwidth, mientras que recibir es gratis.
Para generar una dirección TRC20 por API, llama a POST /api/v2/tron/addresses. La respuesta es una dirección Base58Check que empieza por T. Un webhook registrado con POST /api/v2/tron/webhooks informa después de cada depósito USDT-TRC20 que llegue a ella. Esta página explica primero el formato y luego la creación, la vigilancia y el envío, con endpoints y cuerpos de petición.
Todo lo que sigue se ejecuta contra https://app.chaingateway.io con un token Bearer en la cabecera Authorization. Si añades X-Network: testnet a cualquier llamada, pasa a la testnet de TRON, así que puedes ensayar todo el flujo con TRX de prueba gratuitos. Para una explicación más larga del formato, consulta ¿Qué es una dirección TRC20? en el blog.
¿Qué aspecto tiene una dirección TRC20?
Una dirección TRC20 es la dirección de una cuenta TRON en su forma Base58Check, por ejemplo TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL. Tiene 34 caracteres y empieza por T. La documentación de cuentas de TRON define el valor subyacente como 21 bytes: un byte de prefijo 0x41 y después 20 bytes que coinciden con la dirección de Ethereum derivada de la misma clave pública.
Por eso la misma dirección tiene una grafía hexadecimal de 42 caracteres que empieza por 41. Las API de nodo suelen devolver esa forma, mientras que las wallets y los exploradores muestran la Base58Check. TronWeb convierte entre ambas con tronWeb.address.toHex() y fromHex().
«TRC20» nombra el estándar de tokens, no la dirección. TRC-20 es el estándar de tokens fungibles de TRON y es compatible con ERC-20 de Ethereum a nivel de interfaz. Una dirección TRON guarda TRX y todos los tokens TRC-20.
- La forma Base58Check que muestran las wallets y los exploradores: 34 caracteres, empieza por T.
- El byte de prefijo 41 marca el valor como dirección TRON.
- Los 20 bytes restantes son idénticos a la dirección de Ethereum derivada de la misma clave pública.
- La forma hexadecimal: 42 caracteres en total, tal como la devuelven muchas API de nodo.
¿Es lo mismo una dirección TRC20 que la dirección de un contrato TRC20?
No. La dirección de una wallet es una cuenta controlada por una clave privada. La dirección de un contrato pertenece a código desplegado, y nadie tiene una clave para ella. La documentación de TRON lista ambas como tipos de cuenta, y las dos se escriben como cadenas que empiezan por T, así que nada en la cadena las distingue.
La dirección del contrato identifica qué token se mueve. Nunca es el destino de una transferencia. El contrato TRC-20 de USDT es TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, y los tokens enviados a la dirección de un contrato son, casi siempre, irrecuperables. La guía del blog explica la diferencia con más detalle.
¿Por qué una dirección TRC20 nueva no aparece en Tronscan?
Porque TRON solo reconoce una cuenta tras su activación. Según la documentación de cuentas de TRON, un par de claves recién generado existe en local, pero la dirección no se puede consultar por la API ni en un explorador de bloques hasta que se activa.
La activación ocurre cuando una cuenta existente envía a la dirección nueva cualquier cantidad de TRX o de un token TRC-10, y el remitente paga una comisión de creación de cuenta. La documentación da esa comisión como 1 TRX en mainnet en el momento de escribirla, así que comprueba el valor actual antes de planificar un flujo de pagos en torno a ella. Una dirección generada sirve para depósitos y webhooks, pero no esperes que un explorador la muestre antes de su primera activación.
Endpoints de direcciones TRC20: crear, leer, vigilar, enviar
Cuatro tareas y las rutas que las resuelven. Crear direcciones y registrar webhooks no requiere ninguna clave privada. Solo el envío la requiere.
| Endpoint | Qué hace |
|---|---|
POST /api/v2/tron/addresses | Genera una nueva dirección TRON |
POST /api/v2/tron/addresses/import | Importa una clave privada existente para que la API pueda firmar por esa dirección |
POST /api/v2/tron/addresses/{address} | Cambia la contraseña que cifra una clave almacenada |
DELETE /api/v2/tron/addresses/{address} | Elimina una dirección de tu cuenta |
GET /api/v2/tron/balances/{address} | Saldo de TRX de la dirección |
GET /api/v2/tron/balances/{address}/trc20/{contract_address} | Saldo de un token TRC-20, USDT incluido |
GET /api/v2/tron/balances/{address}/trc10/{token_id} | Saldo de un token TRC-10 |
POST /api/v2/tron/webhooks | Suscribe a las transferencias de TRX, TRC-10, TRC-20 o TRC-721 de la dirección |
GET /api/v2/tron/webhooks/notifications | Lista las notificaciones ya entregadas, para conciliar |
POST /api/v2/tron/transactions/trc20 | Envía un token TRC-20, como USDT, desde la dirección |
Esa es toda la superficie que toca un sistema de depósitos. La referencia completa de TRON, con las 40 operaciones incluidos el staking y la autofirma, está en la página de la API de TRON. El campo type de un webhook y la ruta separada /transactions/trc10 existen porque TRON maneja dos estándares de tokens. La comparación TRC10 frente a TRC20 explica en cuál emitir si lanzas un token en lugar de aceptar uno existente.
¿Cómo genero una dirección TRC20 por REST?
POST /api/v2/tron/addresses crea una. El cuerpo admite un único campo opcional, password, y ese campo decide el modelo de custodia. Si envías una contraseña, la clave privada se guarda cifrada con ella, y las transferencias posteriores se autentican con la contraseña en lugar de la clave. Si la omites, la respuesta te entrega la clave privada directamente, para que la guardes en tu propio vault. La referencia es explícita en que las contraseñas no se almacenan: si la pierdes, la wallet no se puede restaurar. Es la misma frase leída al revés, porque nadie más puede desbloquearla tampoco.
curl -X POST https://app.chaingateway.io/api/v2/tron/addresses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"password": "a-strong-password-per-wallet"}'
Si tu plataforma ya genera las claves por su cuenta, encaja mejor la segunda ruta. POST /api/v2/tron/addresses/import registra una dirección que derivaste en otro sitio, junto con su clave privada y una contraseña de cifrado, y desde entonces la API puede firmar por ella. Las direcciones que solo quieres vigilar no necesitan ninguna de las dos llamadas, porque una suscripción de webhook referencia la dirección como cadena.
Dos rutas de mantenimiento pertenecen al mismo grupo. POST /api/v2/tron/addresses/{address} cambia la contraseña de cifrado de una clave almacenada. DELETE /api/v2/tron/addresses/{address} elimina la dirección de tu cuenta, y la referencia señala que eso también reduce tu recuento de direcciones usadas. Conviene integrarla en la tarea que retira las direcciones de depósito caducadas si estás cerca del límite de un plan.
¿Cómo vigilo una dirección TRC20 para detectar USDT entrante?
Consultar Tronscan periódicamente para detectar depósitos es la versión que se rompe en silencio. POST /api/v2/tron/webhooks es la versión que escala. url es el único campo que la referencia marca como obligatorio. to limita la suscripción a los depósitos en tu dirección, from a las transferencias que salen de ella y contractaddress a un único token. type selecciona la clase de activo y acepta TRX, TRC10, TRC20 o TRC721. reference admite hasta 255 caracteres de tu propio texto, y ahí va el ID del pedido o del cliente, para que la notificación llegue ya con tu clave de búsqueda.
curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-backend.example/hooks/tron",
"to": "TYourDepositAddress",
"type": "TRC20",
"contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"reference": "customer-4711"
}'
Define un secreto personal en tu cuenta y cada entrega llevará una cabecera X-Signature, un HMAC-SHA256 codificado en base64 sobre el txid del payload. Verifícala antes de analizar nada más.
Nada reenvía por sí solo una entrega fallida. GET /api/v2/tron/webhooks/notifications/failed lista lo que no llegó, y POST /api/v2/tron/webhooks/notifications/{id}/retry es la llamada que lo envía de nuevo. Una entrada sale de la lista de fallidas cuando empieza su reintento y vuelve solo si ese reintento también falla. Como un reintento entrega el mismo evento por segunda vez, guarda el hash de transacción de cada depósito acreditado bajo una restricción de unicidad y deja que la base de datos rechace el duplicado. El código de firma y la forma de los payloads están en la guía de webhooks.
¿Cómo envío USDT-TRC20 desde la dirección?
POST /api/v2/tron/transactions/trc20 requiere cuatro campos: from, to, contractaddress y amount. El importe es un número simple en unidades del token, así que 25 USDT es 25, no un valor escalado por los seis decimales del contrato. Junto a ellos envías password, para una clave que la API guarda cifrada, o privatekey, si guardaste tú la clave.
En el campo contractaddress, la diferencia entre la dirección de una wallet y la de un contrato de token se convierte en una regla de integración. La dirección del contrato identifica qué token se mueve y nunca es el destino. La de USDT es TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t y va en contractaddress, nunca en to. Los tokens enviados a la dirección de un contrato son, casi siempre, irrecuperables. La guía del blog explica por qué las dos se ven idénticas: ambas son cadenas que empiezan por T y nada en la cadena las distingue.
Enviar cuesta Energy y Bandwidth, mientras que recibir es gratis, así que un sistema de depósitos paga al barrer los fondos y no al recibir el depósito. La calculadora de comisiones de TRON calcula el coste de una transferencia concreta, y GET /api/v2/tron/chainparameters devuelve los precios vigentes de los recursos, de modo que tu código nunca fija una constante que una votación de gobernanza pueda invalidar.
¿Cómo valido una dirección TRC20 antes de enviar?
Comprueba el destino en el momento en que el usuario lo envía, no después de emitir la transacción. Una dirección TRC-20 tiene 34 caracteres, empieza por T y lleva un checksum Base58Check que se rompe con un solo carácter mal escrito. Así se distingue una cadena bien formada de un error de tecleo sin tocar la red. El validador de direcciones ejecuta esa comprobación para TRC-20, ERC-20 y BEP-20 en el navegador, por si quieres verificar una dirección a mano.
Confundir por accidente una dirección TRON con una EVM es difícil, porque los formatos se distinguen a simple vista. Una cadena con T no pasa la validación de Ethereum y una cadena con 0x no pasa la de TRON. La TVM de TRON ejecuta buena parte del Solidity escrito para la EVM, pero es un entorno de ejecución aparte, con su propia medición de recursos, Energy y Bandwidth en lugar de gas, y su propia codificación de direcciones. Tratar «TRON EVM» como algo literal es donde empiezan los errores de direcciones entre cadenas.
Fuentes
¿Construyes un checkout o el backend de un exchange que necesita direcciones TRC20 a gran escala? Crea una cuenta gratuita y genera un lote en testnet. Prueba de 7 días, sin tarjeta, sin KYC.
Preguntas frecuentes: la API de direcciones TRC20
¿Listo para crear tu primera dirección TRC20?
Crea una cuenta y genera hoy una dirección TRC20 de testnet. Prueba de 7 días, sin tarjeta, sin KYC. La referencia completa de endpoints está en la página de la API de TRON, la pregunta sobre el formato se responde en ¿Qué es una dirección TRC20? y las siete cadenas funcionan con el mismo esquema en la API blockchain multicadena.
Revisado por Maurice Sobiera Cómo escribimos estas páginas