Casos de uso de una API blockchain: seis ejemplos
Seis casos de uso de una API blockchain, con los endpoints de Chaingateway que usa cada uno: pagos, pagos salientes, monederos, monitorización, consultas y NFT.
Revisado por Maurice Sobiera
Una API blockchain es un servicio web que permite a una aplicación crear direcciones, leer saldos, enviar transacciones y recibir notificaciones por HTTPS, sin ejecutar nodos blockchain. Envuelve la interfaz de nodo de bajo nivel, normalmente JSON-RPC, en un conjunto más reducido de llamadas. Los casos de uso siguientes muestran qué llamadas necesita cada uno.
¿Para qué se usa una API blockchain?
Los usos habituales se reducen a seis tareas. Cada una se corresponde con unos pocos endpoints de la API REST de Chaingateway, y el mismo patrón existe en cada red compatible, salvo que se indique lo contrario.
| Caso de uso | Qué hace la aplicación | Endpoints principales (se muestra Ethereum) |
|---|---|---|
| Aceptar pagos cripto | Crea una dirección de depósito por pedido y espera el pago | POST /addresses, POST /webhooks, GET /balances/{address} |
| Pagar o repartir tokens | Envía moneda nativa o tokens a muchas direcciones | POST /transactions, POST /transactions/erc20 |
| Ejecutar el backend de un monedero | Crea, importa y exporta direcciones | POST /addresses, POST /addresses/import, GET /addresses/export/{address} |
| Monitorizar direcciones | Reacciona a las transferencias entrantes y salientes | POST /webhooks, GET /webhooks/notifications |
| Consultar datos de la cadena | Lee bloques, transacciones y recibos | GET /blocks/{block_number}, GET /transactions/{txid} |
| Comprobar NFT | Lee el propietario y la URI de metadatos de un token | GET /nfts/{contract_address}/owner/{token_id} |
Todas las rutas empiezan por /api/v2/{blockchain}, por ejemplo /api/v2/ethereum/addresses. La lista completa está en la referencia de la API.
¿Cómo se aceptan pagos cripto con una API?
Cree una dirección de depósito para cada pedido, registre un webhook para ella y trate el webhook como la señal de que ha llegado un pago. La llamada de dirección devuelve una dirección nueva. La llamada de webhook recibe la dirección (to), una url y un type, como ETH, ERC20 o ERC721, más un reference opcional de hasta 255 caracteres que puede usar como ID de pedido.
# 1. Create a password-protected deposit addresscurl -X POST https://app.chaingateway.io/api/v2/ethereum/addresses \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"password": "a-long-random-password"}'
# 2. Watch it for incoming ERC-20 transferscurl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "0xDepositAddressFromStep1", "contractaddress": "0xTokenContractAddress", "type": "ERC20", "url": "https://shop.example.com/hooks/chaingateway", "reference": "order-10231" }'Cuando aparece una transferencia que coincide, Chaingateway envía una notificación a su URL. Verifique su cabecera X-Signature y confirme el importe en la cadena antes de entregar la mercancía. Los webhooks no se reintentan automáticamente: las notificaciones fallidas aparecen en /webhooks/notifications/failed y pueden reenviarse. Solana no tiene webhooks, así que consulte el endpoint de saldo en su lugar. Nuestra guía de webhooks de pago cubre el flujo completo.
¿Cómo se envían pagos masivos o airdrops?
Llame al endpoint de transacciones una vez por destinatario desde un script. Para tokens, use POST /api/v2/ethereum/transactions/erc20 con el remitente, la dirección del contrato, el receptor y el importe.
Cada transferencia necesita gas en la moneda nativa de la red, en la dirección emisora. Consulte GET /gasprice antes de un lote grande, y envíe las transferencias en secuencia por cada dirección emisora para que los nonce no colisionen. Las transferencias de NFT usan el endpoint erc721, descrito en Transferir NFT mediante API.
¿Puede una API ejecutar el backend de un monedero?
Sí, con límites. Los endpoints de direcciones crean direcciones, y un parámetro password guarda la clave privada cifrada en el servidor, para que pueda enviar con la contraseña en lugar de con la clave. Puede importar una dirección existente y exportar una clave privada más tarde. La guía de gestión de monederos enumera las ventajas y los inconvenientes, y nuestros consejos de seguridad explican por qué los fondos a largo plazo deben estar en almacenamiento en frío.
Los saldos se obtienen con GET /balances/{address} para la moneda nativa, y con GET /balances/{address}/erc20 para los tokens. El endpoint de lista de transacciones muestra solo las transacciones creadas a través de la API de Chaingateway. No indexa todas las transacciones de una dirección, así que use webhooks si también necesita las transferencias entrantes.
¿Cómo se monitorizan direcciones y se consultan datos de la cadena?
Use webhooks para los eventos y los endpoints de consulta para el historial. Los webhooks cubren las direcciones y los contratos que registra. Para lo demás, lea bloques por número, una transacción por hash o una transacción decodificada. Bitcoin tiene sus propios endpoints basados en monederos bajo /api/v2/bitcoin. Si necesita acceso directo al nodo en lugar de estas llamadas, los métodos están documentados en la referencia JSON-RPC de Ethereum y en la referencia RPC de Bitcoin.
¿Qué casos de uso soporta cada red?
El soporte varía según la red, como muestra el archivo OpenAPI. Consulte esta tabla antes de diseñar en torno a una función.
| Red | Webhooks | Transferencias de token | Consulta de propietario y URI de NFT | Modelo de monedero |
|---|---|---|---|---|
| Ethereum, Polygon, Arbitrum | Sí | ERC-20 y ERC-721 | Sí | Direcciones individuales |
| BNB Smart Chain | Sí | BEP-20 y BEP-721 | Sí | Direcciones individuales |
| TRON | Sí | TRC-20 y TRC-721 | No hay endpoint de consulta | Direcciones individuales |
| Solana | No | SPL | Sí | Direcciones individuales |
| Bitcoin | Sí | Solo moneda nativa | No aplica | Monederos que contienen direcciones |
Un flujo de pagos que depende de webhooks necesita, por tanto, una consulta periódica como respaldo en Solana. Un flujo que depende de comprobar la propiedad de NFT necesita otra fuente de datos en TRON.
¿Cómo se prueba un caso de uso sin fondos reales?
Ejecútelo primero en una red de pruebas. Añada la cabecera X-Network: testnet a cualquier solicitud, y el mismo endpoint funciona contra la red de pruebas en lugar de mainnet. Omita la cabecera, o configúrela en mainnet, para volver atrás. Así puede probar la creación de direcciones, una transferencia y el ciclo de un webhook, incluida la verificación de la firma, antes de que intervenga ningún valor real.
Chaingateway tiene una prueba gratuita de 7 días que no requiere tarjeta, y no necesita verificación de identidad para empezar. Los pasos son breves:
- Cree una cuenta y copie su token de API desde el panel.
- Cree una dirección de prueba y fóndela desde un faucet público de la testnet que haya elegido.
- Registre un webhook que apunte a una URL pública de su receptor.
- Envíe una transferencia de prueba y compruebe que llega la notificación y que su firma se verifica.
Nuestra guía de inicio rápido recorre la misma secuencia con ejemplos de código.
¿Qué casos de uso no encajan bien?
Una API como esta no encaja con trabajos que necesitan el historial completo de la cadena de direcciones arbitrarias, como analítica, declaraciones fiscales o decisiones de préstamo. Esos trabajos necesitan un indexador que almacene cada transacción, no un servicio que envía transacciones y le notifica sobre las direcciones que usted registró. Construya o adquiera esa parte por separado, y use la API para el lado de transacciones y notificaciones.
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.