Integración multi-blockchain con una API REST
Cómo integrar varias blockchains con una API REST: redes, endpoints de tokens por cadena, un flujo de depósito y retiro, y las diferencias que quedan.
Revisado por Maurice Sobiera
La integración multi-blockchain significa que un único backend se comunica con varias cadenas mediante una sola interfaz, en lugar de una biblioteca cliente por cadena. Con Chaingateway, usted llama a endpoints REST con un token portador. El mismo patrón cubre Ethereum, BNB Smart Chain, Polygon, Arbitrum, Tron, Bitcoin y Solana, dentro de los límites que fija cada cadena.
¿Qué blockchains y estándares de token cubre la API?
La API cubre siete cadenas, cada una con una testnet. Cambie a la testnet con la cabecera X-Network: testnet. La página de redes compatibles enumera las redes de prueba. Las transferencias de tokens tienen un endpoint por cadena:
| Cadena | Endpoints de tokens y NFT en el archivo OpenAPI | Testnet |
|---|---|---|
| Ethereum | transactions/erc20, transactions/erc721 | Sepolia |
| BNB Smart Chain | transactions/bep20, transactions/bep721 | Testnet de BSC |
| Polygon | transactions/erc20, transactions/erc721 | Amoy |
| Arbitrum | transactions/erc20, transactions/erc721 | Arbitrum Sepolia |
| Tron | transactions/trc20, transactions/trc721, transactions/trc10 | Nile |
| Solana | transactions/SPL | Devnet |
| Bitcoin | transactions (solo moneda nativa) | Testnet3 |
Cada ruta empieza por /api/v2/<chain>/. La lista completa está en el archivo OpenAPI.
¿Cómo se construye sobre ella un servicio de depósitos y retiros?
Un flujo de tipo custodia tiene tres partes: una dirección por cliente, un webhook por dirección y una llamada de retiro. Cada parte es una petición, y cada una tiene la misma forma en cada cadena que la soporte.
- Cree una dirección de depósito. En las cadenas EVM y en Tron, esto es
POST /api/v2/<chain>/addresses, y la respuesta contiene la dirección. Envíe unpasswordpara que la clave se guarde cifrada. Sin contraseña, la respuesta contiene la clave privada y debe guardarla usted mismo. - Registre un webhook para la dirección.
POST /api/v2/<chain>/webhooksrecibe laurldel receptor, la dirección ento, untypecomoERC20oTRC20, y opcionalmente unacontractaddressy unareferencede hasta 255 caracteres. - Pague. Un retiro de un token ERC20 es una sola petición:
curl -X POST https://app.chaingateway.io/api/v2/ethereum/transactions/erc20 \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": "0xHotWalletAddress", "to": "0xCustomerAddress", "contractaddress": "0xTokenContract", "amount": 100, "password": "hot-wallet-password" }'En BNB Smart Chain, sustituya ethereum/transactions/erc20 por bsc/transactions/bep20. En Tron, use tron/transactions/trc20, que recibe los mismos campos salvo los ajustes de gas. Solana es distinto: solana/transactions/SPL requiere el privatekey del remitente y no acepta una contraseña de wallet. El artículo sobre secretos personales explica cómo verificar las notificaciones que recibe.
¿Qué pasa cuando falla una petición?
La API devuelve un cuerpo JSON con status, ok y message. Un 401 con el mensaje «Wrong password provided» significa que la contraseña de la wallet no coincide. Un 422 lleva el error propio del nodo, por ejemplo insufficient funds for gas * price + value. La parte específica de cada cadena es la causa: una transferencia ERC20 en Ethereum necesita ETH para el gas en la dirección remitente, y una transferencia TRC20 necesita energy y bandwidth, o TRX para quemar. Revise los saldos antes de reintentar, porque reintentar no soluciona una comisión que falta.
Las notificaciones de webhook fallidas no se reenvían automáticamente. Enumérelas con GET /api/v2/<chain>/webhooks/notifications/failed y reenvíe cada una con el endpoint de reintento. Una notificación reenviada puede llegar después de otras, así que haga idempotente al receptor con respecto al txid.
¿Qué sigue siendo distinto entre cadenas?
Varias cosas siguen siendo distintas, y la API no las oculta:
- Comisiones: Ethereum, BNB Smart Chain, Polygon y Arbitrum usan gas, con un endpoint
gaspriceen cada una. Tron usa energy y bandwidth. - Webhooks: todas las cadenas excepto Solana.
- Wallets: Bitcoin trabaja con wallets con nombre que contienen varias direcciones, creadas con
POST /api/v2/bitcoin/wallets. - Activos: el mismo token en dos cadenas son dos activos separados, y la API no hace puentes entre ellos.
¿Con qué cadena conviene empezar?
Empiece con la cadena que ya usan sus clientes, y añada otras reutilizando los mismos manejadores. Los formularios de retiro de los exchanges indican la red, por ejemplo ERC-20, BEP-20 o TRC-20. Pregunte a sus primeros clientes en qué red tienen USDT antes de construir la segunda integración.
¿Qué debe guardar por cadena?
Un servicio multi-cadena necesita la cadena en cada registro, porque la misma cadena de caracteres puede ser válida en varias cadenas. Guarde al menos estos campos:
| Campo | Por qué se necesita |
|---|---|
chain y network | Las direcciones 0x son válidas en Ethereum, BNB Smart Chain, Polygon y Arbitrum, y la mainnet y la testnet se parecen |
address en el formato propio de la cadena | Tron usa direcciones Base58 que empiezan por T, y la forma hexadecimal con prefijo 41 aparece en los datos en bruto de los nodos |
contractaddress y type | El mismo token tiene un contrato distinto en cada cadena |
txid | La clave para eliminar duplicados de las notificaciones de webhook y para las consultas |
reference | El ID de su pedido o cliente, definido al registrar el webhook |
| Importe en la unidad base de la cadena | Los decimales varían según el token, así que convierta solo en la capa de presentación |
Añada una restricción de unicidad sobre (chain, network, txid). Concilie con una segunda fuente de forma programada, por ejemplo con la lista de notificaciones fallidas y con un explorador de bloques.
¿Cómo empezar?
Empiece en testnets. Cree una dirección en Sepolia y otra en Nile, registre un webhook para cada una, envíe una transferencia de prueba y compruebe que su receptor gestiona ambas notificaciones. La prueba gratuita de 7 días no requiere tarjeta ni KYC.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.