← Blog
10 min de lectura
|
Publicado
|
Actualizado

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.

Capítulos
C
Chaingateway Team
Expertos en blockchain

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 usoQué hace la aplicaciónEndpoints principales (se muestra Ethereum)
Aceptar pagos criptoCrea una dirección de depósito por pedido y espera el pagoPOST /addresses, POST /webhooks, GET /balances/{address}
Pagar o repartir tokensEnvía moneda nativa o tokens a muchas direccionesPOST /transactions, POST /transactions/erc20
Ejecutar el backend de un monederoCrea, importa y exporta direccionesPOST /addresses, POST /addresses/import, GET /addresses/export/{address}
Monitorizar direccionesReacciona a las transferencias entrantes y salientesPOST /webhooks, GET /webhooks/notifications
Consultar datos de la cadenaLee bloques, transacciones y recibosGET /blocks/{block_number}, GET /transactions/{txid}
Comprobar NFTLee el propietario y la URI de metadatos de un tokenGET /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.

Terminal window
# 1. Create a password-protected deposit address
curl -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 transfers
curl -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.

RedWebhooksTransferencias de tokenConsulta de propietario y URI de NFTModelo de monedero
Ethereum, Polygon, ArbitrumSíERC-20 y ERC-721SíDirecciones individuales
BNB Smart ChainSíBEP-20 y BEP-721SíDirecciones individuales
TRONSíTRC-20 y TRC-721No hay endpoint de consultaDirecciones individuales
SolanaNoSPLSíDirecciones individuales
BitcoinSíSolo moneda nativaNo aplicaMonederos 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:

  1. Cree una cuenta y copie su token de API desde el panel.
  2. Cree una dirección de prueba y fóndela desde un faucet público de la testnet que haya elegido.
  3. Registre un webhook que apunte a una URL pública de su receptor.
  4. 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.

C
Chaingateway Team
Expertos en blockchain

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