Arbitrum API: pagos ERC-20 en la Layer 2 de Ethereum
Envía tokens ERC-20 en Arbitrum con una sola llamada REST. Seguridad de nivel Ethereum a comisiones de Layer-2, con webhooks de depósito integrados.
La Arbitrum API de Chaingateway es una API REST que envía tokens ERC-20 en Arbitrum, la Layer 2 de Ethereum, con una llamada autenticada. Usa las mismas direcciones 0x y el mismo estándar de tokens que Ethereum, con una fracción del gas de mainnet, y manda un webhook en cada depósito. La prueba gratuita de 7 días no requiere KYC.
Arbitrum ejecuta las transacciones de Ethereum en un rollup: la ejecución ocurre en la Layer 2, los datos de la transacción se liquidan en Ethereum, y el presupuesto de seguridad sigue siendo el de Ethereum. Transferencias que no tienen sentido económico en L1 funcionan bien aquí.
Eso importa para los sistemas de pago de una forma específica. Las wallets de depósito necesitan consolidarse en una hot wallet, los reembolsos salen en cantidades pequeñas, y los lotes de pagos consisten en muchas transferencias individuales. En mainnet, cada una de estas operaciones conlleva una comisión que puede superar el importe que se mueve. En Arbitrum las mismas operaciones siguen siendo lo bastante baratas como para ejecutarlas tan a menudo como tu contabilidad lo requiera, no tan raramente como lo permita el esquema de comisiones.
Tres de los endpoints conforman el flujo de pago: importar una dirección, enviar un token ERC-20, leer notificaciones de webhook. La autenticación es un Bearer token en la cabecera Authorization contra https://app.chaingateway.io; la cabecera X-Network: testnet cambia cualquier llamada a la red de pruebas.
¿Cómo llega un depósito en Arbitrum a mi aplicación?
Un depósito en Arbitrum llega a tu aplicación como un webhook firmado: importas una dirección con la API REST, la API vigila Arbitrum y envía la transferencia a tu servidor.
Cómo funciona Arbitrum: el rollup, en breve
Arbitrum es un rollup optimista. Las transacciones se ejecutan en la infraestructura propia de Arbitrum, y la red publica los datos comprimidos de la transacción en Ethereum, donde cualquiera puede reconstruir el estado de la L2 a partir de lo que hay on-chain.
"Optimista" nombra el modelo de seguridad: las actualizaciones de estado se asumen válidas al publicarse, y sigue una ventana de impugnación durante la cual cualquier observador puede presentar una prueba de fraude contra una incorrecta. Ethereum arbitra la disputa. Como los datos subyacentes residen en Ethereum, hacer trampa no se puede ocultar, y la L2 hereda la seguridad de L1 en lugar de arrancar su propio conjunto de validadores.
El diseño también explica la estructura de comisiones. Una comisión de Arbitrum paga por dos cosas: la ejecución en la L2, que es barata, y la parte proporcional de la transacción en la publicación de datos por lotes en Ethereum. Desde marzo de 2024 esos datos van al espacio de blobs introducido por EIP-4844, lo cual es más barato que el calldata ordinario de Ethereum. Cientos de transferencias comparten un único lote, así que cada una carga con una pequeña fracción del coste de L1 en lugar de una comisión completa de transacción de L1.
Arbitrum One frente a Arbitrum Nova
Existen dos chains públicas de Arbitrum, y los nombres se confunden. Arbitrum One es el rollup que acabamos de describir: todos los datos de transacción llegan a Ethereum, y los supuestos de confianza se reducen a los del propio Ethereum.
Arbitrum Nova ejecuta en su lugar el protocolo AnyTrust. Sus datos de transacción los mantiene fuera de la chain un Data Availability Committee, y el sistema se mantiene sólido mientras al menos dos miembros del comité se comporten honestamente; si el comité no consigue servir los datos, la chain recurre al modo rollup completo. Mantener los datos fuera de Ethereum hace que Nova vuelva a ser más barata, al precio de ese supuesto de confianza adicional.
En la práctica la división es clara. Nova alberga aplicaciones de gaming y sociales, cargas de trabajo con recuentos de transacción muy altos y valor bajo por transacción, donde el compromiso del comité es aceptable.
Arbitrum One mantiene los protocolos DeFi, la liquidez de stablecoins y el soporte de exchanges. Cuando una integración de pagos, una página de retiro de un exchange o este artículo dicen "Arbitrum" sin calificativo, se refieren a Arbitrum One. Es la chain donde realmente residen los USDC y USDT de tus usuarios.
Los endpoints de Arbitrum
| Endpoint | Qué hace |
|---|---|
POST /api/v2/arbitrum/addresses | Crea una nueva dirección de depósito |
POST /api/v2/arbitrum/addresses/import | Importa una private key para una dirección existente |
POST /api/v2/arbitrum/transactions/erc20 | Envía un token ERC-20 |
POST /api/v2/arbitrum/webhooks | Crea un webhook de depósito para una dirección |
GET /api/v2/arbitrum/webhooks/notifications | Lista las notificaciones de webhook de tu cuenta |
Ese conjunto cubre depósitos y pagos. Las transferencias nativas de ETH, las consultas de saldo y bloque, el precio del gas, las transacciones decodificadas y los endpoints de reintento de notificaciones fallidas completan el resto de la superficie en la documentación, y los datos a nivel de cuenta vienen de GET /api/account. Si ya usas Chaingateway en Ethereum u otra EVM chain, las llamadas de Arbitrum te resultarán familiares porque siguen el mismo esquema.
Envía un token ERC-20 en Arbitrum
La llamada de transferencia toma el contrato del token, el remitente, el destinatario y el importe, más la contraseña que fijaste al importar la key del remitente. La estimación de gas, la gestión del nonce y la transmisión ocurren en el lado de la API.
curl -X POST https://app.chaingateway.io/api/v2/arbitrum/transactions/erc20 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contractaddress": "0xYourTokenContract",
"from": "0xYourHotWallet",
"to": "0xRecipient",
"amount": 100,
"password": "YourWalletPassword"
}'Esa es la solicitud completa — crea una cuenta y pruébala primero en Arbitrum Sepolia.
¿Cuánto más barata es una transferencia en Arbitrum que en Ethereum?
Más barata, y la diferencia actual está a una llamada de distancia: compara GET /api/v2/ethereum/gasprice con GET /api/v2/arbitrum/gasprice en lugar de fiarte de una cifra fija. Una comisión de Arbitrum paga la ejecución barata en Layer 2 más una parte de los datos por lotes publicados en Ethereum; la documentación de Arbitrum sobre gas y comisiones describe el cálculo.
Ambas redes fijan precios de forma dinámica, así que las cifras absolutas se mueven con el precio de ETH y la carga de red. La subasta de gas en mainnet dispara la comisión precisamente cuando la actividad alcanza su pico, la peor correlación posible para un negocio de pagos.
Para un backend de pagos, la diferencia importa porque las operaciones de pago multiplican las comisiones. Un depósito de un cliente es una transferencia entrante, una consolidación en la hot wallet y eventualmente un pago saliente: tres eventos de comisión por un solo pago.
A precios de mainnet, los equipos responden agrupando consolidaciones y retrasando pagos, y los fondos retrasados aparecen como capital de trabajo varado entre wallets de depósito dispersas. A precios de Arbitrum consolidas según lo programado y pagas bajo demanda, y la línea de comisiones es fácil de absorber.
Los pagos pequeños también vuelven a ser viables. Cuando el gas se lleva una parte grande de una transferencia pequeña, nadie puede fijar precios pequeños en mainnet. Con una comisión menor por transferencia, la facturación por transacción, el uso medido y los pequeños reembolsos pasan a ser prácticos.
¿Funciona mi código de Ethereum sin cambios en Arbitrum?
Sí, para el flujo de pagos. Arbitrum es totalmente EVM-compatible, y para pagos esa frase tiene un significado preciso: el mismo formato de dirección 0x con el mismo checksum EIP-55, la misma interfaz de contrato ERC-20, el mismo esquema de firma. Un contrato de token desplegado en Arbitrum expone la misma función transfer que su homólogo de mainnet. Nada del estándar de token se reinventó para la L2, razón por la cual wallets, exploradores y librerías construidos para Ethereum manejan Arbitrum con solo un endpoint RPC distinto y nada más.
A través de la API esto se reduce a un segmento de ruta. POST /api/v2/ethereum/transactions/erc20 y POST /api/v2/arbitrum/transactions/erc20 aceptan un payload idéntico: contract address, from, to, amount.
Tu lógica de validación, tu manejador de webhook y el esquema de tu base de datos se mantienen tal cual, porque las direcciones y los hashes de transacción tienen la misma forma en ambas chains. La conclusión práctica es una ventaja dicha sin rodeos: la misma llamada de API, una chain distinta. Los equipos que ya ejecutan Ethereum a través de Chaingateway suelen añadir Arbitrum en una tarde, convirtiendo la chain en una columna de una tabla de configuración en lugar de una bifurcación en el código.
Una cosa no se traslada: los saldos. Esa es la siguiente sección.
Los activos tienen que estar primero en Arbitrum
Un saldo ERC-20 es una entrada dentro de un contrato en una chain específica. USDT en Ethereum y USDT en Arbitrum son dos entradas de contrato distintas, y tener una no te da nada de la otra. Antes de que tu hot wallet pueda enviar tokens en Arbitrum, esos tokens tienen que existir en Arbitrum. La API no puede hacerlos aparecer al otro lado; ninguna API puede.
Dos vías habituales los llevan hasta ahí. El bridge de Arbitrum bloquea tokens en Ethereum y acuña su representación en la L2. El mismo mecanismo funciona a la inversa para los retiros de vuelta a L1, y esa dirección incluye la ventana de impugnación, así que mover valor de vuelta a Ethereum a través del bridge canónico tarda alrededor de una semana a menos que pagues a un bridge rápido de terceros para adelantar la liquidez. La vía más simple para la mayoría de operadores: retirar desde un exchange que admita retiros en Arbitrum, lo cual pone los tokens en la L2 en un solo paso y evita por completo la mecánica del bridge.
Presupuesta también el gas. Las comisiones en Arbitrum se pagan en ETH, así que una hot wallet necesita un pequeño saldo de ETH en la L2 junto a sus tokens. Los importes son pequeños, pero una wallet con tokens y cero ETH no puede moverse en absoluto, y ese modo de fallo merece una alerta de monitorización antes que un post-mortem.
Webhooks de depósito en una chain con bloques por debajo del segundo
Arbitrum produce bloques bastante por debajo de un segundo, así que un depósito es visible casi tan pronto como el usuario lo envía. Chaingateway reenvía ese evento a tu backend en lugar de hacerte hacer polling. Fija un secreto personal en tu cuenta y cada entrega de webhook lleva una cabecera X-Signature — un HMAC-SHA256 en base64 del campo txid del payload — para que puedas verificar que viene de Chaingateway. Las entregas que fallan se guardan en una lista de notificaciones fallidas y se pueden reenviar mediante POST /api/v2/arbitrum/webhooks/notifications/{id}/retry.
GET /api/v2/arbitrum/webhooks/notifications devuelve el historial de entregas, útil para auditorías o para reproducir eventos tras un tiempo de inactividad de tu lado. La guía de webhooks cubre la configuración y la verificación de firmas.
¿Cómo acepto depósitos en Arbitrum?
Da a cada cliente una dirección de depósito propia y observa esas direcciones mediante webhooks; observar no requiere ninguna key. Una dirección por cliente hace que los pagos entrantes sean atribuibles sin campos de memo que los usuarios olvidan rellenar.
Del depósito al acreditado
Un cliente envía 200 USDC desde su cuenta de exchange y elige Arbitrum como red de retiro. Los bloques llegan bastante por debajo de un segundo, así que la transferencia queda on-chain casi de inmediato, y Chaingateway envía el evento por POST a tu endpoint.
Tu manejador verifica la firma HMAC, comprueba el contrato del token contra una allowlist, y registra el depósito como pendiente. Una vez que el depósito cumple tu propia política de confirmación, el registro pasa a acreditado. En una chain tan rápida, el cliente experimenta toda la secuencia como instantánea, lo cual vale algo en el checkout: la diferencia entre que "pago recibido" aparezca antes o después de que el usuario empiece a preguntarse si funcionó.
Consolidación y pagos
Luego viene el trabajo de mantenimiento que las comisiones de L1 solían hacer doloroso. Según un calendario, o cada vez que un saldo cruza un umbral, consolidas los depósitos en la hot wallet con POST /api/v2/arbitrum/transactions/erc20, desde la dirección de depósito, hacia la hot wallet.
Con comisiones de Layer 2, esto puede ejecutarse cada hora en lugar de cada semana, manteniendo los fondos concentrados donde el proceso de pago puede alcanzarlos en lugar de repartidos por cientos de direcciones. Los retiros son la misma llamada en la dirección contraria, de hot wallet a la dirección del cliente. Nada en el flujo es específico de Arbitrum salvo el segmento de ruta y el nivel de comisión, y el nivel de comisión es precisamente lo que hace asequible el calendario horario.
Por qué construir pagos en Arbitrum
La compatibilidad total con EVM significa que el conocimiento de Ethereum se traslada uno a uno: los checksums de dirección, los contratos de token y la firma se comportan exactamente como en mainnet. Las comisiones son una fracción de las de Ethereum L1, lo cual convierte las transferencias pequeñas de una pérdida en un redondeo. La seguridad deriva del propio Ethereum, porque los datos de transacción se publican en L1 y el estado incorrecto se puede impugnar allí. Y el ecosistema no es una apuesta de futuro: grandes protocolos DeFi operan en Arbitrum en producción hoy mismo, así que la liquidez, los exploradores y el soporte de wallets ya existen.
Cualquier token en Arbitrum, incluido el tuyo
Chaingateway admite los tokens estándar en Arbitrum, tanto stablecoins consolidadas como activos puenteados y lanzamientos personalizados. La integración es la misma en cada chain admitida: constrúyela una vez, y apunta ese mismo código a /api/v2/ethereum/, /api/v2/polygon/ o /api/v2/bsc/ cuando expandas. La visión general de la blockchain API lista las siete chains.
Construido para cada patrón de pago
Los casos de uso coinciden con las demás EVM chains: flujos de checkout que aceptan stablecoins con liquidación en segundos, monitorización de depósitos para plataformas de trading, procesamiento de retiros desde una hot wallet, airdrops y calendarios de vesting, facturación recurrente para SaaS, transferencias transfronterizas. Donde Arbitrum destaca es en los casos que los precios de mainnet dejan fuera: micropagos, consolidaciones de alta frecuencia y direcciones de depósito por usuario que cada una necesita transacciones de mantenimiento ocasionales.
La mayoría de los equipos no construyen el soporte de Arbitrum desde cero. Lo añaden como segunda chain a una integración de Chaingateway ya existente, reutilizan la misma ruta de código y cambian de chain por solicitud.
Testnet: la misma API contra Arbitrum Sepolia
Añade X-Network: testnet a cualquier solicitud y se ejecuta contra la red de pruebas; la testnet pública de Arbitrum es Arbitrum Sepolia, y el ETH de prueba sale gratis de los faucets. Las rutas, los payloads y las formas de respuesta no cambian, así que el código con el que ensayas es, byte por byte, el código que despliegas.
Ejecuta el ciclo completo de depósito al menos una vez antes de mainnet: transferencia entrante, entrega de webhook, verificación de firma, consolidación. Los errores que merece la pena detectar, un manejador que calcula el HMAC sobre el campo de payload equivocado, o un endpoint al que un balanceador de carga hace timeout, se comportan de forma idéntica en testnet y en producción. La única diferencia es lo que te cuestan. Salir a producción es borrar la cabecera.
Cuando fallan las solicitudes
Los errores de cliente y los de servidor requieren tratamientos opuestos. Un 4xx significa que la solicitud en sí está mal formada, un token caducado, una dirección malformada, un importe que la wallet no puede cubrir, y reintentar la misma solicitud repite el rechazo; regístralo y corrige la entrada. Un 5xx o un timeout de red no dice nada sobre tu entrada, así que reintenta con backoff exponencial y un tope.
El caso para el que hay que diseñar es el timeout ambiguo en un envío. Tu cliente HTTP se rindió, pero la transferencia puede haber salido de todas formas, y reenviar a ciegas es cómo suceden los pagos duplicados.
Antes de cualquier reintento de una transferencia, comprueba qué salió realmente, GET /api/v2/arbitrum/transactions lista las transferencias creadas mediante la API, y reenvía solo cuando el primer intento haya fallado de forma verificable. Construye esa comprobación en el worker de pagos desde el primer día. Cuesta un GET adicional por reintento y ahorra la conversación mucho más cara en la que le pides a un cliente que te devuelva un pago duplicado.
Tres pasos hacia producción
Obtén tu API key. Regístrate y la key está disponible de inmediato; la prueba de 7 días no requiere KYC.
Haz tu primera solicitud. El quickstart recorre la primera dirección y la primera transferencia.
Configura los webhooks y sal a producción. Suscribe tu backend a los eventos de depósito, como se muestra en la guía de webhooks, y luego elimina la cabecera X-Network: testnet. Los planes y límites están en la página de precios.
Qué funciona en cada chain
Arbitrum hereda el esquema de solicitud ERC-20 de Ethereum y, a través del rollup, la seguridad de Ethereum. La tabla siguiente lo sitúa junto a las otras seis chains que cubre la API.
| Chain | Direcciones | Transferencias de tokens | Webhooks de depósito |
|---|---|---|---|
| Bitcoin | POST /api/v2/bitcoin/wallets/{wallet}/addresses | — (sin estándar de token) | GET /api/v2/bitcoin/webhooks/notifications |
| Ethereum | POST /api/v2/ethereum/addresses/import | ERC-20: POST /api/v2/ethereum/transactions/erc20 | GET /api/v2/ethereum/webhooks/notifications |
| TRON | POST /api/v2/tron/addresses/import | TRC-20 y TRC-10: POST /api/v2/tron/transactions/trc20 y .../trc10 | GET /api/v2/tron/webhooks/notifications |
| Solana | POST /api/v2/solana/addresses | SPL: POST /api/v2/solana/transactions/SPL | — |
| BNB Smart Chain | POST /api/v2/bsc/addresses/import | BEP-20: POST /api/v2/bsc/transactions/bep20 | GET /api/v2/bsc/webhooks/notifications |
| Polygon | POST /api/v2/polygon/addresses/import | ERC-20: POST /api/v2/polygon/transactions/erc20 | GET /api/v2/polygon/webhooks/notifications |
| Arbitrum | POST /api/v2/arbitrum/addresses/import | ERC-20: POST /api/v2/arbitrum/transactions/erc20 | GET /api/v2/arbitrum/webhooks/notifications |
Dos notas al pie para leer bien la tabla. Primero: TRON es la integración más profunda de la plataforma. Más allá de las rutas anteriores, la documentación cubre staking (POST /api/v2/tron/freeze y /delegate), parámetros de la chain, y un par de auto-firma — /transactions/trc20/build para construir una transacción y /transactions/broadcast para enviar una que hayas firmado localmente. Si tu equipo de cumplimiento insiste en que las private keys nunca salgan de tus servidores, ese patrón de construir y transmitir es tu vía de entrada.
Segundo: un guion significa que la documentación actual no recoge una ruta v2 para esa celda, no que la red sea de segunda categoría. Bitcoin no tiene estándar de token, de ahí la celda de token vacía — el BTC nativo funciona con su propio modelo de wallet en su lugar: crea una wallet cifrada con contraseña con POST /api/v2/bitcoin/wallets, deriva direcciones de depósito bajo ella, y envía con POST /api/v2/bitcoin/transactions. La documentación de Solana cubre creación de direcciones, transferencias de SOL y SPL, y consultas de saldo y bloque, pero aún sin webhooks. Para cualquier cosa no listada aquí, la referencia de la API tiene el estado actual.
Fuentes y lecturas adicionales
Estas fuentes primarias documentan los estándares y el comportamiento de la chain descritos en esta página:
- Inside Arbitrum Nitro: documentación de Arbitrum, trata cómo el rollup ejecuta y liquida las transacciones.
- Gas and fees: documentación de Arbitrum, trata cómo se calculan las comisiones.
- Differences between Arbitrum and Ethereum: Overview: documentación de Arbitrum.
- ERC-20: Token Standard: la especificación de la interfaz de tokens.
FAQ: Arbitrum API
¿Listo para integrar Arbitrum?
Crea una cuenta en app.chaingateway.io/register, envía una transferencia ERC-20 de testnet y configura tu primer webhook. La referencia de endpoints está en la documentación, y planes y límites de tasa tienen su propia página.
Revisado por Maurice Sobiera Cómo escribimos estas páginas