Una Blockchain API para Pagos Cripto, Siete Chains
Acepta y envía pagos cripto en Bitcoin, Ethereum, TRON, Solana, BNB Smart Chain, Polygon y Arbitrum. Una única API REST para wallets, transferencias de tokens y webhooks de depósito.
Chaingateway es una API REST para pagos blockchain. Generas direcciones de wallet y envías tokens con llamadas HTTPS sencillas, y cuando un depósito llega a una de tus direcciones, un webhook notifica a tu servidor en tiempo real. La misma API cubre Bitcoin, Ethereum, TRON, Solana, BNB Smart Chain, Polygon y Arbitrum.
Esa cobertura importa más que cualquier función individual. La mayoría de las blockchain APIs gestionan una sola red; los equipos que añaden una segunda chain suelen terminar con una segunda base de código, porque cada red tiene su propio formato RPC y sus propias librerías cliente. Chaingateway elimina esa fragmentación. La ruta para una transferencia ERC-20 en Ethereum es POST /api/v2/ethereum/transactions/erc20; en Polygon es POST /api/v2/polygon/transactions/erc20. Cambia un segmento de ruta y tu código existente se ejecuta en la siguiente chain.
No hay ningún nodo que sincronizar ni ningún SDK que instalar. La autenticación es un Bearer token en la cabecera Authorization. Una cabecera adicional, X-Network: testnet, apunta cualquier llamada a la red de pruebas en lugar de mainnet. Una prueba gratuita de 7 días empieza sin KYC.
Lo que cubre la API
Wallets y direcciones
Crea wallets protegidas con contraseña para Ethereum, BSC, Polygon y TRON, o trae keys existentes mediante endpoints de importación como POST /api/v2/ethereum/addresses/import. Las private keys se guardan cifradas con una contraseña que solo tú conoces — Chaingateway no guarda ni las keys ni las contraseñas en texto plano, así que sin tus credenciales, los fondos permanecen donde están. Las direcciones de Solana provienen de POST /api/v2/solana/addresses. Para productos de pago, el patrón habitual es una dirección por cliente o por factura, lo cual hace que la atribución sea trivial: lo que llegue a la dirección X pertenece al cliente X, sin necesidad de emparejar por importe o memo.
Transacciones nativas y de tokens
Envía ETH, BNB, POL, TRX o BTC con una sola llamada, y mueve tokens ERC-20, BEP-20, TRC-20 y SPL a través de la misma interfaz. Gas, precio del gas y nonce son campos opcionales de la solicitud — omítelos y la API los rellena, así que pasas un destinatario y un importe en lugar de ensamblar transacciones en bruto. Los importes son unidades de token, no unidades base: 100 significa 100 tokens del contract address que sea que hayas indicado. TRON va más allá que las demás chains: los endpoints freeze y delegate cubren el staking (con unfreeze y undelegate para revertirlo), y TRC-10 convive junto a TRC-20.
Datos blockchain decodificados
Las respuestas llegan como JSON legible, no como hex. Una transacción decodificada de TRON incluye remitente, destinatario, el importe en unidades de token, el número de bloque y el recuento de confirmaciones actual. Eso es lo que una blockchain data API debería devolver: valores que tu aplicación puede almacenar y mostrar sin un parser de ABI.
Webhooks para pagos entrantes
Suscríbete a eventos on-chain y recibe una notificación en cuanto un depósito se liquida on-chain. Fija un secreto personal en tu perfil y cada notificación llevará una cabecera X-Signature que tu servidor puede verificar. Las entregas que fallaron las lista la API y se pueden reenviar con una sola llamada.
Qué funciona en cada chain
La tabla condensa la documentación actual de la API en una sola vista: qué chains tienen rutas de direcciones, qué estándares de token puedes enviar, y dónde están documentados los webhooks de depósito.
| 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.
Un ejemplo de blockchain API: la primera llamada en cuatro lenguajes
Consigue una API key (siguiente sección), luego confirma que funciona. GET /api/account devuelve los detalles de tu cuenta y demuestra que la key es válida.
curl https://app.chaingateway.io/api/account \
-H "Authorization: Bearer YOUR_API_KEY"Esa es toda la comprobación de autenticación — crea una cuenta y la misma llamada demuestra que tu propia key funciona.
Cómo obtener una API key para blockchain
Regístrate en app.chaingateway.io/register. La prueba de 7 días empieza sin KYC.
Copia la API key de tu panel.
Envíala con cada solicitud como Authorization: Bearer YOURAPIKEY, y mantenla solo en el servidor. El código del lado del cliente la expondría a cualquiera que abra la consola del navegador. El panel de la cuenta puede además restringir la key a las direcciones IP de tus servidores, para que una key filtrada sea inútil en cualquier otro sitio. Más medidas de refuerzo están en nuestros consejos de seguridad para la blockchain API.
Recibir depósitos: el flujo de webhook
Una integración de pagos suele verse así:
Crea o importa una dirección de depósito para cada cliente.
El cliente envía monedas o tokens a esa dirección.
Una vez que la transferencia se liquida, Chaingateway envía por POST una notificación a tu URL de callback — con una cabecera X-Signature si has fijado un secreto personal.
Tu servidor verifica la firma y acredita la cuenta del cliente.
Seguridad de webhooks en la práctica
Un endpoint de webhook es una puerta hacia tu backend, y esta puerta en concreto acredita dinero. Chaingateway te da tres mecanismos para protegerla; un manejador de producción debería usar los tres. Esto aplica a las seis chains con webhooks de depósito — la detección de depósitos de Solana usa polling en su lugar, cubierto más abajo.
1. Verifica la firma
Fija un secreto personal en la configuración de tu perfil — a partir de entonces cada notificación llevará una cabecera X-Signature, construida como base64 de un HMAC-SHA256 sobre el campo txid del payload, con ese secreto como key. Recalcúlala a partir del txid recibido, compárala con el valor de la cabecera antes de acreditar nada, y usa una comparación en tiempo constante — la mayoría de librerías estándar incluyen una. Rechaza los fallos con un 401. Esto cierra el ataque obvio: cualquiera que descubra tu URL de callback puede enviar por POST depósitos fabricados hacia ella, y sin comprobación de firma tu tienda enviaría mercancía por pagos que nunca ocurrieron.
2. Diseña para el reenvío
Una notificación puede llegarte más de una vez — puedes reenviar las fallidas a través de la API, y nada garantiza entrega exactamente una vez entre medias. Basa tu lógica de acreditación en el hash de transacción en lugar de en el número de callbacks recibidos — un INSERT ... ON CONFLICT DO NOTHING sobre la columna del hash cuesta una línea y elimina toda esa clase de errores de doble acreditación. Responde con un 2xx en cuanto la notificación quede persistida y haz el procesamiento lento después; un manejador que hace trabajo pesado en línea se topa con timeouts y convierte un depósito en un caso de soporte.
3. Usa las rutas de recuperación
Si tu endpoint estuvo caído o respondió con un error, la entrega queda en la lista de fallidas: GET /api/v2/{chain}/webhooks/notifications/failed muestra lo que no llegó, y POST /api/v2/{chain}/webhooks/notifications/{id}/retry reenvía cada una a tu orden. Para todo lo demás — un failover de base de datos, un mal despliegue, un certificado TLS caducado — GET /api/v2/{chain}/webhooks/notifications devuelve el historial completo de entregas, así que un trabajo de conciliación nocturno puede compararlo con tu contabilidad y reparar las brechas. Los detalles del payload y el código de verificación están en la guía de webhooks.
Prueba en testnet, despliega el mismo código
Cada ruta acepta una cabecera adicional, X-Network: testnet, y se ejecuta contra la red de pruebas en lugar de mainnet. Los endpoints, cuerpos de solicitud y formas de respuesta se mantienen idénticos; las monedas no tienen valor. Esa última propiedad es la clave. Tus pruebas de integración pueden crear direcciones, mover tokens y recibir webhooks todo el día sin tocar fondos reales.
Una configuración práctica se ve así. Pon la cabecera detrás de una variable de entorno, para que staging la envíe y producción no lo haga — sin diferencia de código entre ambos. Da a staging su propia URL de callback, de lo contrario los depósitos de prueba caen en tu manejador de webhook de producción y confunden la contabilidad. Las monedas de prueba salen gratis de los faucets públicos que cada ecosistema mantiene; la página de redes soportadas en la documentación nombra la red de pruebas por chain — Sepolia para Ethereum, Nile para TRON, Amoy para Polygon, testnet3 para Bitcoin.
Cuando el flujo funcione de principio a fin — dirección creada, depósito detectado, webhook verificado, saldo acreditado — elimina la cabecera. Nada más cambia. Esa simetría es deliberada, y es la razón por la que salir a producción es un cambio de configuración en lugar de un segundo proyecto de integración.
Tres integraciones, paso a paso
Las listas de funciones dicen poco sobre el esfuerzo de integración, así que aquí tienes tres construcciones que vemos a menudo, cada una reducida a sus piezas móviles.
Depósitos para una tienda online
Una tienda quiere aceptar USDT en el checkout. Cuando un cliente elige cripto, tu backend asigna una dirección para ese pedido y la muestra junto al importe. A partir de ahí, el webhook hace el trabajo. La notificación llega en cuanto la transferencia se liquida on-chain; marca el pedido como "pago detectado" y muéstraselo al cliente, porque una respuesta rápida es lo que hace que el checkout con cripto se sienta confiable. Si tu política quiere más profundidad para importes grandes, comprueba la transacción con GET /api/v2/{chain}/transactions/{txid} hasta alcanzar tu umbral, y luego marca el pedido como pagado e inicia el envío.
Dos casos límite deciden si esta construcción está lista para producción. Pago insuficiente: los clientes a veces envían un poco menos que la factura, normalmente porque su wallet dedujo las comisiones de red del importe introducido. Decide la tolerancia de antemano — absorber una diferencia pequeña, o retener el pedido y pedir la diferencia. El pago en exceso es más raro y más fácil: acredítalo o reembólsalo, pero regístralo de todas formas. Ambos casos surgen de comparar el importe notificado con el importe de la factura, en lugar de tratar cualquier callback como "pagado".
Pagos por lotes
Una plataforma de afiliados paga a cientos de socios en stablecoins cada mes, en Polygon porque ahí las comisiones se mantienen pequeñas en relación con los importes de pago. La construcción es una cola y un bucle:
import requests
payouts = load_pending_payouts() # [{"address": ..., "amount": ...}, ...]
for p in payouts:
r = requests.post(
"https://app.chaingateway.io/api/v2/polygon/transactions/erc20",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"contractaddress": "0xTokenContract...",
"from": "0xTreasuryWallet...",
"to": p["address"],
"amount": p["amount"],
"password": "treasury-wallet-password",
},
)
record_result(p, r.json()) # persist before the next iteration
La cola importa más que el bucle. Persiste el estado de cada pago antes de enviarlo, guarda la respuesta de la API de inmediato, y nunca reintentes un envío solo porque la llamada HTTP hizo timeout — la transacción puede haberse completado de todas formas. Comprueba tus resultados guardados y GET /api/v2/polygon/transactions, que lista cada transacción creada mediante la API, y reenvía solo lo que verificablemente nunca ocurrió. Esa única regla separa los sistemas de pago que sobreviven auditorías de los que terminan en arqueología de hojas de cálculo.
Facturación on-chain para un SaaS
Una herramienta B2B factura a sus clientes mensualmente en stablecoins porque los procesadores de tarjetas siguen rechazando su categoría de comercio. La construcción reutiliza el patrón de la tienda con un matiz: una dirección de depósito nueva por factura, no por cliente. La dirección por factura hace trivial la coincidencia — cualquier importe que llegue a la dirección de la factura 4711 pertenece a la factura 4711 — y elimina la incertidumbre de emparejar pagos por importe cuando dos facturas coinciden en la misma suma. El webhook marca las facturas como pagadas; un trabajo programado caduca las antiguas y envía recordatorios. Nada en este flujo requiere una interfaz de wallet, una extensión de navegador ni ningún conocimiento cripto por parte del cliente más allá de la capacidad de enviar una transferencia.
Blockchains soportadas
Cada chain tiene su propia página con endpoints y ejemplos de código:
- Bitcoin API — la chain original. Transferencias nativas de BTC desde wallets cifradas con contraseña, más webhooks de depósito para pagos entrantes.
- Ethereum API — la plataforma de smart contracts más adoptada, con transferencias de tokens ERC-20 y soporte para NFTs ERC-721.
- TRON API — transacciones TRC-10 y TRC-20, staking mediante freeze y delegate, y rutas de auto-firma build/broadcast. Estima los costes de transferencia por adelantado con la calculadora de comisiones de TRON.
- Solana API — creación de direcciones y transacciones de tokens SPL en una chain de alto rendimiento.
- BNB Smart Chain API — transferencias BEP-20 con el mismo patrón de ruta que usas en Ethereum.
- Polygon API — transferencias ERC-20 en la chain de escalado de Ethereum, a una fracción del coste de gas de mainnet. Esta es la blockchain API de Polygon, no el servicio de datos bursátiles de Polygon.io.
- Arbitrum API — L2 de Ethereum para alto rendimiento, compartiendo el diseño de endpoints de mainnet.
Migrar de JSON-RPC a REST
Una blockchain API reemplaza las llamadas JSON-RPC en bruto con una única solicitud REST autenticada por acción. Donde JSON-RPC necesita varios round trips por transferencia, además de codificación manual de ABI, seguimiento de nonce y firma, una llamada como POST /api/v2/{chain}/transactions/erc20 (bep20 en BNB Smart Chain) condensa todo eso en una única solicitud.
Muchos equipos llegan aquí con una integración ya en marcha: web3.js contra un endpoint RPC de pago, o un cliente JSON-RPC hecho a mano de una era anterior de la base de código. La migración es menos dramática de lo que suena, porque la API absorbe categorías enteras de código en lugar de reemplazarlo llamada por llamada.
Toma la ruta de envío canónica en EVM. Sobre JSON-RPC, una transferencia de token es una secuencia: eth_getTransactionCount para el nonce, eth_gasPrice o una llamada de historial de comisión para el precio, eth_estimateGas contra calldata codificado en ABI, firma local, y luego eth_sendRawTransaction para transmitir. Cada paso tiene modos de fallo que tu código gestiona actualmente — o silenciosamente no gestiona. Los cinco se condensan en un único POST autenticado a /api/v2/{chain}/transactions/erc20, y la contabilidad de nonces, la fuente habitual de tickets de "transacción atascada", desaparece por completo de tu base de código.
La detección de eventos cambia de forma más que de lógica. Donde hacías polling a eth_getLogs con un cursor de bloque o mantenías abierta una suscripción WebSocket a través de cada error de reconexión, ahora registras un webhook y eliminas el poller. Tu lógica posterior — analizar la transferencia, emparejar al cliente, acreditar el saldo — se mantiene igual; solo el lado de la entrada pasa de pull a push.
Lo que no se traslada: herramientas de consenso, indexadores personalizados, cualquier cosa que necesite acceso a bloques en bruto. Mantén un endpoint RPC para esos trabajos; ambos coexisten sin fricción. Los pagos suelen ser la primera carga de trabajo que merece la pena migrar, porque conllevan el mayor riesgo operativo por línea de código. La comparación más extensa, incluidos los casos en los que gana un nodo, está en blockchain API vs. blockchain node.
Cuando una solicitud falla
El manejo de errores para una API de pagos merece más que un bloque catch genérico, porque una solicitud fallida y una transacción fallida son eventos distintos.
La capa HTTP sigue las convenciones REST. Un 401 significa que el Bearer token falta, está mal o ha caducado — corrige la credencial, no reintentes. Otras respuestas en el rango 4xx dicen que la solicitud en sí tiene la culpa: una dirección malformada, un campo ausente, un error de validación. Registra el cuerpo de la respuesta, que nombra el problema específico, y trata estos casos como errores que corregir en lugar de condiciones transitorias que reintentar. El rango 5xx y los timeouts a nivel de red forman la clase transitoria, donde un reintento con backoff exponencial es el reflejo correcto.
Con una excepción, y es la excepción que importa. Nunca reintentes a ciegas una solicitud que mueve fondos. Un timeout te dice que no recibiste la respuesta — no que la transacción fallara. La secuencia segura: comprueba si la transferencia salió, usando tus resultados guardados y GET /api/v2/{chain}/transactions (la lista de transacciones que creó tu key), y reenvía solo cuando puedas demostrar que nunca ocurrió. Las claves de idempotencia de tu lado, ligadas a tus propios IDs de pago o pedido, hacen esa comprobación barata.
Construye observabilidad desde el primer día. Registra los pares de solicitud y respuesta para cada llamada que mueve dinero, y alerta sobre tasas de 4xx además de solo sobre 5xx — un repunte repentino de errores de validación suele significar que un despliegue rompió el formato de tu solicitud. Detectarlo en minutos en lugar de días es la diferencia entre un incidente y una nota a pie de página.
¿Ejecutar tus propios nodos o usar una API?
Ejecutar nodos tú mismo te da control total y ninguna dependencia de terceros. También significa una máquina por chain, presupuestos de disco y ancho de banda, monitorización de sincronización y actualizaciones de versión — multiplicado por siete si quieres la cobertura descrita arriba. Nuestra comparación de blockchain API vs. blockchain node recorre esa disyuntiva. La versión corta: ejecuta un nodo cuando necesites control a nivel de consenso, usa la API cuando necesites que los pagos funcionen esta semana.
Preguntas frecuentes
¿Listo para aceptar pagos cripto?
Crea una cuenta en app.chaingateway.io/register, elige una chain de las siete anteriores y envía una transferencia de testnet. La referencia completa de endpoints está en la documentación, y planes y límites de tasa tienen su propia página.