← Blog
10 min de lectura
|
Publicado
|
Actualizado

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.

Capítulos
C
Chaingateway Team
Expertos en blockchain

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:

CadenaEndpoints de tokens y NFT en el archivo OpenAPITestnet
Ethereumtransactions/erc20, transactions/erc721Sepolia
BNB Smart Chaintransactions/bep20, transactions/bep721Testnet de BSC
Polygontransactions/erc20, transactions/erc721Amoy
Arbitrumtransactions/erc20, transactions/erc721Arbitrum Sepolia
Trontransactions/trc20, transactions/trc721, transactions/trc10Nile
Solanatransactions/SPLDevnet
Bitcointransactions (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.

  1. 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 un password para que la clave se guarde cifrada. Sin contraseña, la respuesta contiene la clave privada y debe guardarla usted mismo.
  2. Registre un webhook para la dirección. POST /api/v2/<chain>/webhooks recibe la url del receptor, la dirección en to, un type como ERC20 o TRC20, y opcionalmente una contractaddress y una reference de hasta 255 caracteres.
  3. Pague. Un retiro de un token ERC20 es una sola petición:
Terminal window
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 gasprice en 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:

CampoPor qué se necesita
chain y networkLas 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 cadenaTron 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 typeEl mismo token tiene un contrato distinto en cada cadena
txidLa clave para eliminar duplicados de las notificaciones de webhook y para las consultas
referenceEl ID de su pedido o cliente, definido al registrar el webhook
Importe en la unidad base de la cadenaLos 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.

C
Chaingateway Team
Expertos en blockchain

El equipo de Chaingateway se dedica a simplificar la integración blockchain para desarrolladores de todo el mundo.