Ethereum API: Transferencias ERC-20 con Una Sola Llamada REST

JSON-RPC es el protocolo nativo de cada nodo de Ethereum, y para algunos trabajos (herramientas de consenso, indexación personalizada) quieres ese nivel de acceso. Nuestra guía sobre interactuar con nodos vía JSON-RPC muestra cómo se ve eso en PHP, Python y JavaScript.

Contar los round trips deja clara la idea. Una transferencia de token sobre JSON-RPC en bruto toca al menos cuatro métodos — eth_gasPrice, eth_estimateGas, eth_getTransactionCount y eth_sendRawTransaction — con codificación ABI y firma de transacción entre medias.

Para pagos, la abstracción vale la pena. En la solicitud de transacción de Chaingateway, gas limit, gas price y nonce son campos opcionales — omítelos y la API los rellena al construir y transmitir la transacción; pásalos explícitamente cuando quieras control. Tu parte del intercambio es una única solicitud HTTP que puedes escribir en cualquier lenguaje con una librería estándar.

Si hoy mantienes una integración con web3.js, aquí está la comparación honesta. Una transferencia ERC-20 mediante la librería se ve más o menos así:

// web3.js against your own RPC endpoint
const { Web3 } = require("web3");
const web3 = new Web3("https://your-rpc-endpoint");

const token = new web3.eth.Contract(ERC20_ABI, "0xdAC17F958D2ee523a2206206994597C13D831ec7");
const data = token.methods.transfer(recipient, amountInBaseUnits).encodeABI();

const tx = {
  from: sender,
  to: token.options.address,
  data,
  gas: await web3.eth.estimateGas({ from: sender, to: token.options.address, data }),
  gasPrice: await web3.eth.getGasPrice(),
  nonce: await web3.eth.getTransactionCount(sender),
};

const signed = await web3.eth.accounts.signTransaction(tx, PRIVATE_KEY);
await web3.eth.sendSignedTransaction(signed.rawTransaction);

Más allá de lo que cabe en el fragmento, este código posee un archivo ABI, convierte importes legibles en unidades base a mano (te equivocas en los decimales y envías una millonésima parte de la suma prevista, o un millón de veces más), y mantiene una private key en bruto en memoria de la aplicación. La versión REST es el único POST de arriba: importe como cadena decimal, decimales gestionados del lado del servidor, key cifrada en reposo detrás de una contraseña.

La migración no necesita un fin de semana de reescritura. Ambos estilos son llamadas sencillas, así que ejecútalos en paralelo: enruta los nuevos flujos de pago por REST, deja las interacciones de contrato personalizadas en web3.js, y retira la librería donde ya no se gane su complejidad. Los equipos que usaban web3.js solo para transferencias y comprobaciones de saldo suelen eliminar la dependencia por completo.

Cada transacción de Ethereum quema gas, pagado en ETH por la dirección remitente, nunca por el destinatario. Una wallet con miles de USDT pero cero ETH no puede enviar un solo token, porque el contrato ERC-20 no tiene forma de cubrir su propio coste de ejecución. Recibir tokens no cuesta nada al destinatario.

Este detalle atrapa a más integraciones ERC-20 que cualquier otro. Si tus transferencias impulsadas por la API vienen de una wallet de tesorería, esa wallet necesita un saldo de ETH junto a sus tokens, y recargarla pertenece a la lista de tareas operativas junto a la renovación de certificados.

Cuánto cuesta el gas

Una transferencia simple de ETH cuesta exactamente 21.000 de gas — una constante del protocolo. Una transferencia ERC-20 ejecuta código de contrato y cuesta un múltiplo de eso, con la cifra exacta variando según el contrato del token. El precio por unidad flota con la demanda: desde la actualización London de 2021, la comisión se divide en una base fee que la red quema y una propina de prioridad al proponente del bloque, y ambas suben bajo congestión. La consecuencia práctica: la misma transferencia de USDT cuesta centavos un domingo tranquilo y considerablemente más durante un mint popular.

Lo que la API gestiona por ti

Gas limit, gas price y los topes de EIP-1559 (maxFeePerGas, maxPriorityFeePerGas) son campos opcionales de la solicitud — omítelos y la API los rellena al construir tu transacción, o fíjalos por solicitud cuando quieras el control. Dos cosas siguen siendo responsabilidad tuya: mantener ETH en las wallets remitentes, y decidir dónde tienen sentido económico las transferencias pequeñas — cuando las comisiones de mainnet se acercan al importe de la transferencia, la misma llamada en Polygon o Arbitrum está a un cambio de ruta de distancia.

Recibir es gratis

Una dirección de depósito no necesita ETH para aceptar tokens. El gas se vuelve tu problema solo cuando los fondos salen — incluido cuando consolidas depósitos de clientes en una wallet de tesorería, que es en sí misma una transacción saliente desde cada dirección de depósito.

Desde el cambio a proof of stake, el ritmo de Ethereum es fijo en lugar de estadístico. Los bloques llegan en slots de doce segundos, 32 slots forman una época de 6,4 minutos, y un bloque se finaliza tras aproximadamente dos épocas — llámalo 13 minutos — una vez que dos tercios del ETH en staking lo ha atestiguado (parámetros del protocolo a mediados de 2026). Finalizado significa que la red no puede revertir el bloque sin destruir una gran parte de todo el ETH en staking, lo cual lo sitúa en una categoría distinta de la liquidación probabilística de Bitcoin.

Para la lógica de pagos, la línea temporal se lee así: una transferencia suele incluirse en un bloque en segundos a un minuto; cada slot adicional añade seguridad; tras unos 13 minutos es final en el sentido estricto. La mayoría de aplicaciones acreditan depósitos bastante antes de la finalidad — la inclusión más un puñado de bloques cubre los importes habituales — mientras que los exchanges suelen retener los grandes retiros hasta la finalización. El webhook de depósito te da el evento on-chain; dónde fijas el umbral de acreditación es una línea de política en tu configuración, no en la nuestra.

USDT, USDC, DAI y los demás tokens consolidados funcionan de fábrica, con importes en unidades de token en lugar de unidades base en bruto. ¿Lanzas tu propio ERC-20? Aporta el contract address y el mismo endpoint lo envía. Sin proceso de listado, sin esperas. El contexto sobre el propio estándar está en nuestra guía del estándar ERC-20 token.

• Es la plataforma de smart contracts más adoptada, probada en batalla desde 2015.
• El ecosistema DeFi es el mayor de cualquier chain, con miles de dApps con las que integrarse.
• El precio del gas es dinámico, basado en la demanda de red; puedes dejar los campos de comisión a la API o limitarlos por solicitud con los parámetros de EIP-1559.
• El trabajo de escalado continúa, y Polygon y Arbitrum están disponibles a través de la misma API cuando las comisiones de mainnet aprietan.

El patrón de ruta ERC-20 se repite en las redes EVM: /api/v2/polygon/transactions/erc20, /api/v2/arbitrum/transactions/erc20, y /api/v2/bsc/transactions/bep20 para BNB Smart Chain. El código escrito para Ethereum se traslada editando la ruta. Cuando el gas de mainnet se vuelve demasiado caro para transferencias pequeñas, moverlas a Polygon es un cambio de una línea. La lista completa de chains está en la visión general de la blockchain API.

Los bloques de construcción anteriores cubren la mayoría de patrones de producción que vemos: flujos de checkout que aceptan USDT o USDC, exchanges que acreditan depósitos y procesan retiros a escala, proyectos de tokens que distribuyen mediante airdrops o calendarios de vesting, y negocios de suscripción que facturan en stablecoins cada mes. Todos se reducen a las mismas dos llamadas: enviar una transacción, recibir un webhook.

Checkout en stablecoins para una tienda online

El cliente elige "pagar con USDT" y tu backend asigna una dirección de depósito para el pedido — una dirección por factura, así que la atribución nunca depende de emparejar importes. Muestra la dirección con el importe, y luego espera el webhook. Cuando llega la notificación, cambia el pedido a "pago detectado" para que el comprador vea una respuesta rápida; acredítalo una vez que la transacción tenga la profundidad que tu política exige (la sección de finalidad anterior te da las cifras). Un caso límite pertenece al código desde el primer día: las wallets que restan comisiones del importe introducido producen pagos ligeramente insuficientes, y tu tolerancia ante eso debería ser un valor de configuración, no un ticket de soporte.

Retiros para una plataforma de trading

Los usuarios piden pagos; tu trabajo es enviar muchas transferencias ERC-20 de forma fiable. Pon cada retiro en cola en tu base de datos con una columna de estado, y luego recorre la cola con POST /api/v2/ethereum/transactions/erc20 — una solicitud por pago, registrando la respuesta antes de pasar al siguiente. La regla que mantiene contentos a los auditores: una llamada HTTP que hizo timeout no es una transacción fallida. Verifica contra tus registros y GET /api/v2/ethereum/transactions, que lista cada transacción creada mediante la API, antes de reenviar nada, o pagarás a alguien dos veces. Monitoriza también el saldo de ETH de la wallet de tesorería, ya que cada transferencia saliente quema gas, y alerta con antelación en lugar de cuando la cola se atasque.

Aquí existen dos capas de fallo: errores HTTP de la API, y condiciones on-chain que tu lógica tiene que absorber.

El lado HTTP sigue la convención. Un 401 significa que la key falta o es inválida — un problema de configuración, no un candidato a reintentar. Otras respuestas 4xx dicen que la solicitud está mal: una dirección malformada, un contrato desconocido, un campo ausente. Registra el cuerpo de la respuesta y corrige el llamador. Los reintentos con backoff pertenecen solo a las respuestas 5xx y a los timeouts de red.

El lado de la chain es donde el código de pagos se gana el sueldo. Una transferencia desde una wallet sin ETH suficiente para el gas falla aunque el saldo de tokens sea amplio — monitoriza los saldos de gas de forma proactiva en lugar de descubrirlos vacíos en un mensaje de error. La congestión puede retrasar la inclusión; eso es un retraso, no un fallo, y tu interfaz debería distinguir ambos. Y la regla del recorrido de retiros merece repetirse, porque protege contra el error más caro de este dominio: nunca reenvíes una transferencia solo porque la respuesta HTTP nunca llegó. Confirma primero que realmente no ocurrió.

Para depósitos, crea el hábito de conciliar. GET /api/v2/ethereum/webhooks/notifications lista lo que se entregó; una comparación nocturna contra tu contabilidad detecta cualquier cosa que un error o una interrupción se haya tragado, mientras la solución sigue siendo barata.

Añade X-Network: testnet a cualquier solicitud y se ejecuta en la red de pruebas. Rutas, cuerpos de solicitud y formatos de respuesta se mantienen idénticos a mainnet, lo cual significa que tus pruebas de integración ejercitan la ruta de código real en lugar de mocks. Financia una wallet de prueba desde un faucet público, ejecuta transferencias, recibe webhooks — el ciclo completo no cuesta nada.

Organízalo para que la cabecera venga de la configuración: staging la fija, producción no, y no existe diferencia de código entre ambos. Da también a staging una URL de callback separada, o los depósitos de prueba caerán en tu manejador de webhook de producción. Salir a producción es entonces la eliminación de una cabecera, deliberadamente anticlimática.