Cómo enviar tokens ERC-20: métodos con monedero, código y API

Three routes converge at a token contract

Puede enviar tokens ERC-20 de tres formas: desde una aplicación de cartera, desde su propio código con una biblioteca como ethers.js, o a través de una API REST que firma y transmite por usted. Las tres hacen lo mismo por debajo. Llaman a la función transfer en el contrato inteligente del token, y el remitente paga la comisión de red en ETH, no en el token. Esta guía cubre cada método, los errores que provocan la pérdida de fondos y qué cambia cuando pasa de una transferencia manual a miles de transferencias automatizadas.

TL;DR

Una transferencia ERC-20 es una llamada al contrato del token, no una transferencia de valor simple como ETH. La dirección del destinatario y la cantidad van en los datos de la llamada.
La cartera emisora necesita ETH para el gas aunque tenga muchos tokens. Con cero ETH la transacción falla.
Nunca transfer tokens directamente a un contrato que no tiene código para gestionarlos. Use approve y transferFrom para interacciones con contratos.
En el código, gestione los decimales del token y los tokens que no devuelven un booleano estándar. Envuelva las llamadas con una biblioteca segura.
Si crea una aplicación que envía tokens para usuarios, una API REST elimina el trabajo con el nodo, el nonce y el gas. Lo cubrimos a continuación.

Tabla de contenidos

Qué ocurre realmente cuando envía un token ERC-20
Antes de enviar: una lista de comprobación breve
Método 1: Enviar desde una cartera
Método 2: Enviar con código (ethers.js)
Método 3: Enviar a través de una API REST
Formas comunes en que fallan las transferencias ERC-20
Transferencias sin gas y meta-transacciones
Nuestra perspectiva: trate una transferencia como un flujo de trabajo, no como una llamada
Automatización de transferencias con Chaingateway
Confirmación de que la transferencia funcionó
Preguntas frecuentes
Fuentes

Qué ocurre realmente cuando envía un token ERC-20

Enviar ETH mueve valor nativo entre dos cuentas. Enviar un token ERC-20 cambia un registro de saldos almacenado dentro del contrato del token. Su cartera crea una transacción dirigida al contrato del token, y ese contrato actualiza los saldos del remitente y del destinatario.

El estándar ERC-20 define los métodos que expone todo token conforme: totalSupply, balanceOf, transfer, transferFrom, approve y allowance. Esa interfaz compartida es la razón por la que una cartera o un fragmento de código puede gestionar miles de tokens diferentes. La especificación original es EIP-20, publicada en noviembre de 2015.

De este diseño se derivan algunas consecuencias:

El campo to de la transacción es el contrato del token, no la persona a la que está pagando. El destinatario real se codifica en los datos de la llamada.
Los datos de la llamada comienzan con el selector de función 0xa9059cbb (la firma de transfer), seguidos de la dirección del destinatario y la cantidad, según la documentación ERC-20 de ethereum.org.
ERC-20 es un estándar de token, no lo mismo que Ethereum. ETH es la moneda nativa de la red. Los tokens como USDT son contratos que se ejecutan en ella. Si desea una visión más amplia sobre el gas y ETH, consulte nuestra visión general de Ethereum.

El mismo formato también existe en otras cadenas EVM. Nuestra publicación sobre el estándar de token ERC20 profundiza en cómo funciona, y la guía de direcciones ERC20 explica el formato de dirección y la consulta de saldos.

Antes de enviar: una lista de comprobación breve

La mayoría de las transferencias perdidas provienen de una preparación omitida, no de un fallo técnico. Compruebe estos puntos primero.

Usted posee el token y la cantidad correcta. Confirme el saldo con balanceOf o en su monedero.
Usted posee ETH para el gas. La comisión se paga en la moneda nativa de la red, no se deduce de los tokens que envía. En Polygon o BNB Chain se aplica la misma lógica con la moneda nativa de esa cadena. Un monedero con tokens pero sin ETH no puede enviar nada.
Usted tiene la dirección exacta del destinatario. Cópiela y péguela en lugar de escribirla. El centro de ayuda de MetaMask advierte sobre el envenenamiento de direcciones, donde un atacante introduce en su historial una dirección parecida.
Usted conoce la red. El mismo formato de dirección funciona en varias cadenas EVM. Un token enviado en la red equivocada no llega donde el destinatario lo espera.
El destinatario puede aceptarlo. Enviar a una dirección de depósito de un exchange en la red equivocada, o a un contrato que no puede gestionar tokens, puede suponer una pérdida permanente.
Usted prueba primero con una cantidad pequeña. Para un destinatario nuevo o una integración nueva, envíe una cantidad pequeña y confirme que llegó antes de enviar el importe total.

Método 1: Enviar desde un monedero

Para transferencias puntuales, un monedero es la ruta más sencilla. La guía de Etherscan para enviar ETH o tokens describe el mismo flujo que siguen la mayoría de los monederos:

Abra el monedero y elija la opción de enviar.
Seleccione el token que desea enviar. Si el monedero no lo lista, añádalo pegando la dirección del contrato del token.
Pegue la dirección del destinatario.
Introduzca la cantidad.
Revise la comisión de red. El monedero la estima por usted.
Confirme y, a continuación, siga el hash de la transacción en un explorador de bloques hasta que se confirme.

Dos detalles hacen tropezar a la gente. Primero, la dirección del contrato del token que pega al añadir un token personalizado debe ser la real, porque los tokens falsos usan el mismo nombre y símbolo. Verifíquela en el sitio oficial del proyecto. Segundo, la comisión mostrada está en ETH, por lo que el saldo de ETH del monedero debe cubrirla además de cualquier ETH que pretenda enviar.

Método 2: Enviar con código (ethers.js)

Los desarrolladores que necesiten automatizar transferencias pueden llamar al contrato directamente. El tutorial de ethereum.org sobre el envío de tokens con ethers.js muestra el patrón básico. Una guía independiente de ethers.js explica la diferencia clave con ETH: la transacción no envía valor, llama a la función transfer del token con un destino y una cantidad.

Los pasos son los siguientes:

Cree un proveedor conectado a un nodo de Ethereum (el suyo propio o un endpoint alojado).
Cree un firmante a partir de una clave privada o una billetera que controle.
Instancie el contrato del token con su dirección y un ABI mínimo que contenga transfer, balanceOf y decimals.
Convierta la cantidad legible por humanos a unidades base usando los decimales del token.
Llame a transfer(destinatario, cantidad) y espere el recibo.

Ese tutorial de ethers.js señala que la biblioteca puede enviar una transacción EIP-1559 sin configuración manual de gas, eligiendo un límite de gas y una tarifa de prioridad predeterminada. También puede gestionar el nonce cuando se usa un firmante.

Gestione los decimales correctamente

Los tokens almacenan las cantidades como enteros. Un token con 18 decimales representa 1,0 token como 1000000000000000000 unidades base. El campo decimals forma parte del estándar, pero diferentes tokens establecen diferentes valores, y el texto de EIP-20 lo trata como metadatos opcionales. Lea siempre decimals del contrato en lugar de asumir 18. Codificar el valor incorrecto envía una cantidad errónea por órdenes de magnitud.

No confíe ciegamente en el valor de retorno

El estándar dice que transfer devuelve un booleano. No todos los tokens en la naturaleza se comportan así. Algunos no devuelven nada, y otros fallan de formas inesperadas. La interfaz IERC20 de OpenZeppelin es la referencia del estándar, y la biblioteca SafeERC20 de OpenZeppelin existe para envolver las llamadas de modo que los tokens extraños no rompan su lógica. Si su contrato inteligente mueve tokens, úsela. Si su backend envía tokens, verifique el estado del recibo de la transacción y el evento Transfer emitido en lugar de asumir el éxito.

Límites de gas

Una transferencia simple de ETH usa un límite de gas de 21.000, según la guía de MetaMask. Una transferencia de token es una llamada a contrato, por lo que necesita más. Estime el gas con la llamada de estimación de su biblioteca antes de cada envío en lugar de codificar un número, porque el coste depende del código del contrato del token y del estado de los saldos involucrados.

Método 3: Enviar a través de una API REST

Ejecutar la ruta de código anterior está bien para un script. En un producto se convierte en una lista de tareas: operar o alquilar acceso a nodos, gestionar claves, rastrear nonces para que los envíos concurrentes no colisionen, estimar gas, reintentar transacciones atascadas, decodificar logs para averiguar si llegó un pago, y repetir todo por cadena.

Una API unificada quita esa capa a su equipo. Con Chaingateway usted crea billeteras, envía tokens y lee datos de transacciones decodificados mediante llamadas REST simples. No necesita web3.js ni ethers.js en su pila, y no ejecuta nodos. Nuestra página de API de Ethereum muestra cómo funciona el envío de ERC-20 sobre REST. Las solicitudes se firman con HMAC, y el gas se estima automáticamente.

Method 3: Send through a REST API — overview diagram

El mismo enfoque se extiende a Bitcoin, Tron, Solana, Polygon, BNB Chain y Arbitrum, por lo que una segunda cadena no implica una segunda integración. Si más adelante añade USDT en Tron, lea nuestra explicación sobre TRC10 vs TRC20. Para direcciones de BNB Chain, consulte la guía de direcciones BEP20.

Cuándo encaja cada método

Situación	Monedero	Su propio código	API REST
Transferencia personal puntual	Mejor	Excesivo	Excesivo
Script ocasional en una cadena	Lento	Bueno	Bueno
Pagos o retiradas dentro de una app	Poco práctico	Posible, usted lo mantiene	Mejor opción
Varias cadenas y estándares de token	Manual por cadena	Un cliente por cadena	Una interfaz
Detección de pagos entrantes	Manual	Usted construye escuchas de logs	Webhooks

Formas habituales en que fallan las transferencias ERC-20

Enviar tokens a un contrato

La función transfer no fue diseñada para depositar en contratos inteligentes. Si un contrato no tiene lógica para reaccionar a los tokens entrantes, estos permanecen en su saldo sin forma de recuperarlos. La página de ERC-20 de ethereum.org describe este riesgo, incluidos los tokens enviados al propio contrato del token, e informa de millones de dólares perdidos de esta manera a partir de junio de 2024. Si escribe contratos, añada una función que le permita recuperar tokens enviados por error. Si necesita que un contrato reciba tokens de un usuario, el patrón estándar es: el usuario llama a approve para el contrato y, a continuación, el contrato llama a transferFrom.

Cero ETH para gas

La transacción falla si el remitente no tiene moneda nativa, por muchos tokens que haya en el monedero. Los equipos de producto suelen descubrir esto tarde: un usuario recibe tokens, intenta moverlos y no puede. Las opciones son recargar el monedero con una pequeña cantidad de ETH o diseñar una solución alternativa con autorizaciones firmadas.

Red incorrecta o dirección incorrecta

Las cadenas de bloques no revierten transacciones. Verifique la red y la dirección antes de confirmar y utilice una pequeña transferencia de prueba para cualquier cosa nueva.

Confundir el token con la red

USDT, por ejemplo, existe en varias cadenas. Cuando alguien dice que tiene USDT, pregunte en qué red. La dirección puede parecer idéntica en cada una, pero los fondos residen solo en una cadena.

Transferencias sin gas y meta-transacciones

Una opción creciente para la incorporación de usuarios es permitir que el usuario firme un mensaje y que otra persona envíe la transacción y pague el gas. EIP-3009, Transfer With Authorization, define funciones que permiten a un titular delegar el pago de gas y ejecutar transferencias mediante firmas EIP-712. Solo los tokens cuyos contratos lo implementen admiten esto, así que compruébelo antes de diseñar un flujo en torno a ello. Para una startup, puede eliminar el obstáculo inicial de adquirir ETH para la primera transferencia.

Nuestra perspectiva: trate una transferencia como un flujo de trabajo, no como una llamada

Our perspective: treat a transfer as a workflow, not a call — overview diagram

Observamos el mismo patrón en los equipos que integran el envío de tokens por primera vez. La llamada transfer en sí lleva una tarde. Las semanas se van en todo lo que la rodea: saber cuándo un pago realmente ha llegado, gestionar una transacción fallida o atascada, estimar comisiones y mantener las claves seguras.

Nuestra visión es que enviar y recibir pertenecen juntos. Un flujo de pagos sin eventos de confirmación le obliga a hacer polling, y un flujo de depósitos sin datos decodificados le obliga a analizar logs en bruto. Por eso hemos creado la creación de carteras, transferencias de tokens, estimación de gas, datos de transacciones decodificados y notificaciones webhook detrás de una sola API, firmada con HMAC. Usted obtiene un único contrato con su infraestructura en lugar de uno por cadena, y no ejecuta nodos.

Nuestro consejo práctico: empiece con una transferencia pequeña en un entorno de prueba, verifique decimales y recibos, suscríbase a eventos para la confirmación y solo entonces escale el volumen.

— Bitblade

Automatización de transferencias con Chaingateway

Si está creando pagos, retiradas o depósitos en una aplicación, puede probar nuestra Blockchain API y combinarla con Chaingateway Webhooks para recibir notificaciones cuando llegan los pagos. Los planes en nuestra página de precios comienzan en 49 EUR al mes para Plus, con Pro a 99 EUR al mes, Premium a 249 EUR al mes y Enterprise a 499 EUR al mes. La facturación anual es de 490 EUR para Plus, 990 EUR para Pro, 2490 EUR para Premium y 4990 EUR para Enterprise. El acceso de pago sigue a una prueba gratuita.

Confirmación de que la transferencia funcionó

Enviar una transacción no es lo mismo que completar un pago. Después de enviar:

Guarde el hash de la transacción inmediatamente.
Compruebe el estado del recibo. Una transacción minada puede haber fallado igualmente.
Busque el evento Transfer del contrato del token con el remitente, destinatario y cantidad esperados. El evento forma parte de la interfaz ERC-20.
Espere tantas confirmaciones como exija su política de riesgo antes de entregar bienes o acreditar un saldo.
Concilie contra balanceOf periódicamente para detectar cualquier cosa que su listener haya pasado por alto.

El polling funciona para un script pequeño. Para producción, suscribirse a notificaciones significa que su sistema reacciona a eventos en lugar de preguntar repetidamente.

Preguntas frecuentes

¿Necesito ETH para enviar tokens ERC-20?

Sí. La comisión de red se paga en ETH, no en el token que envía. Si la cartera emisora no tiene ETH, la transacción falla. En otras cadenas EVM, necesita la moneda nativa de esa cadena en su lugar.

¿Es USDT un token ERC-20?

USDT existe en una versión ERC-20 en Ethereum, y es uno de los tokens más utilizados construidos sobre el estándar. También existe en otras redes, así que confirme siempre en qué red está enviando y cuál espera el destinatario.

¿Es ERC-20 lo mismo que Ethereum?

No. Ethereum es la cadena de bloques, y ETH es su moneda nativa. ERC-20 es una interfaz estándar que siguen los contratos de tokens en Ethereum, para que carteras y aplicaciones puedan tratar diferentes tokens de la misma manera.

¿Qué ocurre si envío tokens ERC-20 a una dirección de contrato?

Si el contrato receptor no tiene lógica para gestionar tokens entrantes, estos suelen quedar atascados, y la recuperación depende de si ese contrato incluye una función de rescate. Verifique el destinatario antes de enviar. Para interacciones con contratos, use approve seguido de transferFrom.

¿Puedo enviar tokens ERC-20 sin ejecutar un nodo?

Sí. Puede utilizar una billetera para envíos manuales, o una API REST si está desarrollando una aplicación. Con una API, el proveedor gestiona el acceso al nodo, el flujo de firma y la estimación de gas, y su código realiza peticiones HTTP ordinarias.