Casi d'uso di un'API blockchain: sei esempi
Sei casi d'uso di un'API blockchain con gli endpoint Chaingateway necessari: pagamenti, payout, wallet, monitoraggio, ricerche e controlli sugli NFT.
Verificato da Maurice Sobiera
Un’API blockchain è un servizio web che permette a un’applicazione di creare indirizzi, leggere saldi, inviare transazioni e ricevere notifiche tramite HTTPS, senza gestire nodi blockchain. Racchiude l’interfaccia di basso livello del nodo, di solito JSON-RPC, in un insieme più piccolo di chiamate. I casi d’uso qui sotto mostrano quali chiamate richiede ciascuno.
A che cosa serve un’API blockchain?
Gli usi più comuni si riducono a sei compiti. Ciascuno corrisponde a pochi endpoint dell’API REST di Chaingateway, e lo stesso schema esiste su ogni rete supportata, salvo dove indicato.
| Caso d’uso | Che cosa fa l’applicazione | Endpoint principali (esempio Ethereum) |
|---|---|---|
| Accettare pagamenti crypto | Creare un indirizzo di deposito per ogni ordine e attendere il pagamento | POST /addresses, POST /webhooks, GET /balances/{address} |
| Inviare payout o airdrop di token | Inviare monete native o token a molti indirizzi | POST /transactions, POST /transactions/erc20 |
| Gestire il backend di un wallet | Creare, importare ed esportare indirizzi | POST /addresses, POST /addresses/import, GET /addresses/export/{address} |
| Monitorare indirizzi | Reagire ai trasferimenti in entrata e in uscita | POST /webhooks, GET /webhooks/notifications |
| Consultare i dati della chain | Leggere blocchi, transazioni e ricevute | GET /blocks/{block_number}, GET /transactions/{txid} |
| Verificare gli NFT | Leggere il proprietario e l’URI dei metadati di un token | GET /nfts/{contract_address}/owner/{token_id} |
Tutti i percorsi iniziano con /api/v2/{blockchain}, per esempio /api/v2/ethereum/addresses. L’elenco completo si trova nel riferimento API.
Come si accettano pagamenti crypto con un’API?
Si crea un indirizzo di deposito per ogni ordine, si registra un webhook per quell’indirizzo e si considera il webhook come segnale che il pagamento è arrivato. La chiamata per l’indirizzo restituisce un nuovo indirizzo. La chiamata per il webhook richiede l’indirizzo (to), un url e un type come ETH, ERC20 o ERC721, più un reference opzionale di massimo 255 caratteri, che si può usare come ID dell’ordine.
# 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" }'Quando compare un trasferimento corrispondente, Chaingateway invia una notifica al vostro URL. Si verifica l’header X-Signature, poi si confronta l’importo con la chain prima di rilasciare la merce. I webhook non vengono ritentati automaticamente: le notifiche non riuscite sono elencate sotto /webhooks/notifications/failed e possono essere inviate di nuovo. Solana non ha webhook, quindi per questo caso si interroga invece l’endpoint del saldo. La nostra guida ai webhook per i pagamenti descrive il flusso completo.
Come si inviano payout o airdrop?
Si chiama l’endpoint delle transazioni una volta per destinatario da uno script. Per i token si usa POST /api/v2/ethereum/transactions/erc20 con mittente, indirizzo del contratto, destinatario e importo.
Ogni trasferimento richiede gas nella moneta nativa della rete, presente sull’indirizzo mittente. Prima di un lotto grande si controlla GET /gasprice, e si inviano i trasferimenti in sequenza per ogni indirizzo mittente, così che i nonce non entrino in collisione. I trasferimenti di NFT usano l’endpoint erc721, descritto in Trasferire NFT tramite API.
Un’API può gestire il backend di un wallet?
Sì, entro certi limiti. Gli endpoint per gli indirizzi creano indirizzi, e un parametro password conserva la chiave privata cifrata sul server, così che l’invio possa avvenire con la password invece che con la chiave. Si può importare un indirizzo esistente ed esportare in seguito una chiave privata. La guida alla gestione dei wallet elenca i compromessi, e i nostri consigli di sicurezza spiegano perché i fondi a lungo termine vanno conservati in cold storage.
I saldi arrivano da GET /balances/{address} per la moneta nativa e da GET /balances/{address}/erc20 per i token. L’endpoint dell’elenco delle transazioni mostra solo le transazioni create tramite l’API Chaingateway. Non indicizza ogni transazione di un indirizzo, quindi se servono anche i trasferimenti in entrata conviene usare i webhook.
Come si monitorano indirizzi e si consultano i dati della chain?
Per gli eventi si usano i webhook, per la cronologia gli endpoint di ricerca. I webhook coprono gli indirizzi e i contratti registrati. Per il resto si leggono blocchi per numero, una transazione per hash oppure una transazione decodificata. Bitcoin ha endpoint propri basati sul wallet sotto /api/v2/bitcoin. Se invece servono accessi diretti al nodo al posto di queste chiamate, i metodi sono documentati nel riferimento JSON-RPC di Ethereum e nel riferimento RPC di Bitcoin.
Quali reti supportano quale caso d’uso?
Il supporto varia da rete a rete, come mostra il file OpenAPI. Consultate questa tabella prima di progettare intorno a una funzione.
| Rete | Webhook | Trasferimenti di token | Ricerca di proprietario e URI NFT | Modello di wallet |
|---|---|---|---|---|
| Ethereum, Polygon, Arbitrum | Sì | ERC-20 e ERC-721 | Sì | Indirizzi singoli |
| BNB Smart Chain | Sì | BEP-20 e BEP-721 | Sì | Indirizzi singoli |
| TRON | Sì | TRC-20 e TRC-721 | No, non c’è un endpoint di ricerca | Indirizzi singoli |
| Solana | No | SPL | Sì | Indirizzi singoli |
| Bitcoin | Sì | Solo moneta nativa | Non applicabile | Wallet che contengono indirizzi |
Un flusso di pagamento basato sui webhook richiede quindi un meccanismo di polling di riserva su Solana. Un flusso che si basa sulla verifica della proprietà degli NFT richiede una fonte dati diversa su TRON.
Come si prova un caso d’uso senza fondi reali?
Si esegue prima su una rete di test. Si aggiunge l’header X-Network: testnet a qualsiasi richiesta, e lo stesso endpoint funziona sulla rete di test invece che sulla mainnet. Per tornare indietro si toglie l’header oppure lo si imposta su mainnet. Così si possono provare la creazione di un indirizzo, un trasferimento e un ciclo completo con webhook, inclusa la verifica della firma, prima che sia coinvolto valore reale.
Chaingateway offre una prova gratuita di 7 giorni che non richiede carta di credito, e per iniziare non serve una verifica dell’identità. I passaggi sono brevi:
- Creare un account e copiare il token API dalla dashboard.
- Creare un indirizzo di test e finanziarlo con un faucet pubblico della rete di test scelta.
- Registrare un webhook che punti a un URL pubblico del proprio ricevitore.
- Inviare un trasferimento di prova e verificare che la notifica arrivi e che la firma sia valida.
La nostra guida rapida illustra la stessa sequenza con esempi di codice.
Quali casi d’uso non sono adatti?
Un’API di questo tipo non è adatta ai lavori che richiedono l’intera cronologia della chain di indirizzi arbitrari, come analisi, dichiarazioni fiscali o decisioni di credito. Questi compiti richiedono un indicizzatore che memorizzi ogni transazione, non un servizio che invia transazioni e notifica sugli indirizzi registrati. Questa parte va costruita o acquistata separatamente, mentre l’API serve per il lato delle transazioni e delle notifiche.
Come scriviamo questi articoli
Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.