Una Blockchain API per i pagamenti crypto, sette chain
Accetta e invia pagamenti crypto su Bitcoin, Ethereum, TRON, Solana, BNB Smart Chain, Polygon e Arbitrum. Un'unica API REST per wallet, trasferimenti di token e webhook di deposito.
Chaingateway è un'API REST per pagamenti blockchain. Generi indirizzi wallet e invii token con semplici chiamate HTTPS, e quando un deposito raggiunge uno dei tuoi indirizzi, un webhook notifica il tuo server in tempo reale. La stessa API copre Bitcoin, Ethereum, TRON, Solana, BNB Smart Chain, Polygon e Arbitrum.
Quella copertura conta più di qualsiasi singola funzionalità. La maggior parte delle blockchain API gestisce una sola rete; i team che aggiungono una seconda chain finiscono di solito con una seconda codebase, perché ogni rete ha il proprio formato RPC e le proprie librerie client. Chaingateway elimina questa frammentazione. La rotta per un trasferimento ERC-20 su Ethereum è POST /api/v2/ethereum/transactions/erc20; su Polygon è POST /api/v2/polygon/transactions/erc20. Cambia un segmento di percorso e il tuo codice esistente gira sulla chain successiva.
Non c'è alcun nodo da sincronizzare né alcun SDK da installare. L'autenticazione è un Bearer token nell'header Authorization. Un header aggiuntivo, X-Network: testnet, punta qualsiasi chiamata sulla rete di test invece che su mainnet. Una prova gratuita di 7 giorni parte senza KYC.
Cosa copre l'API
Wallet e indirizzi
Crea wallet protetti da password per Ethereum, BSC, Polygon e TRON, oppure importa key esistenti tramite endpoint di importazione come POST /api/v2/ethereum/addresses/import. Le private key vengono memorizzate cifrate con una password che solo tu conosci — Chaingateway non conserva né key né password in chiaro, quindi senza le tue credenziali i fondi restano al loro posto. Gli indirizzi Solana arrivano da POST /api/v2/solana/addresses. Per i prodotti di pagamento, il pattern abituale è un indirizzo per cliente o per fattura, il che rende l'attribuzione banale: qualsiasi cosa arrivi all'indirizzo X appartiene al cliente X, senza abbinamento per importo o memo.
Transazioni native e di token
Invia ETH, BNB, POL, TRX o BTC con una singola chiamata, e sposta token ERC-20, BEP-20, TRC-20 e SPL attraverso la stessa interfaccia. Gas, prezzo del gas e nonce sono campi opzionali della richiesta — omettili e l'API li compila, quindi passi un destinatario e un importo invece di assemblare transazioni grezze. Gli importi sono unità di token, non unità base: 100 significa 100 token del contract address che hai fornito. TRON va oltre le altre chain: gli endpoint freeze e delegate coprono lo staking (con unfreeze e undelegate per invertirlo), e TRC-10 convive accanto a TRC-20.
Dati blockchain decodificati
Le risposte arrivano come JSON leggibile, non hex. Una transazione TRON decodificata include mittente, destinatario, l'importo in unità di token, il numero di blocco e il conteggio attuale delle conferme. Questo è ciò che una blockchain data API dovrebbe restituire: valori che la tua applicazione può memorizzare e mostrare senza un parser ABI.
Webhook per i pagamenti in entrata
Sottoscrivi eventi on-chain e ricevi una notifica appena un deposito si liquida on-chain. Imposta un secret personale nel tuo profilo e ogni notifica porterà un header X-Signature che il tuo server può verificare. Le consegne fallite vengono elencate dall'API e possono essere reinviate con una singola chiamata.
Cosa funziona su quale chain
La tabella condensa la documentazione API attuale in un'unica vista: quali chain hanno rotte per gli indirizzi, quali standard di token puoi inviare, e dove sono documentati i webhook di deposito.
| Chain | Indirizzi | Trasferimenti di token | Webhook di deposito |
|---|---|---|---|
| Bitcoin | POST /api/v2/bitcoin/wallets/{wallet}/addresses | — (nessuno standard token) | GET /api/v2/bitcoin/webhooks/notifications |
| Ethereum | POST /api/v2/ethereum/addresses/import | ERC-20: POST /api/v2/ethereum/transactions/erc20 | GET /api/v2/ethereum/webhooks/notifications |
| TRON | POST /api/v2/tron/addresses/import | TRC-20 e TRC-10: POST /api/v2/tron/transactions/trc20 e .../trc10 | GET /api/v2/tron/webhooks/notifications |
| Solana | POST /api/v2/solana/addresses | SPL: POST /api/v2/solana/transactions/SPL | — |
| BNB Smart Chain | POST /api/v2/bsc/addresses/import | BEP-20: POST /api/v2/bsc/transactions/bep20 | GET /api/v2/bsc/webhooks/notifications |
| Polygon | POST /api/v2/polygon/addresses/import | ERC-20: POST /api/v2/polygon/transactions/erc20 | GET /api/v2/polygon/webhooks/notifications |
| Arbitrum | POST /api/v2/arbitrum/addresses/import | ERC-20: POST /api/v2/arbitrum/transactions/erc20 | GET /api/v2/arbitrum/webhooks/notifications |
Due note a piè di pagina per leggere correttamente la tabella. Primo: TRON è l'integrazione più profonda della piattaforma. Oltre alle rotte sopra, la documentazione tratta lo staking (POST /api/v2/tron/freeze e /delegate), i parametri di chain, e una coppia di self-signing — /transactions/trc20/build per costruire una transazione e /transactions/broadcast per inviarne una firmata localmente. Se il tuo team compliance insiste che le private key non lascino mai i tuoi server, quel pattern build-and-broadcast è la tua via d'ingresso.
Secondo: un trattino significa che la documentazione attuale non riporta alcuna rotta v2 per quella cella, non che la rete sia di serie B. Bitcoin non ha uno standard token, da cui la cella token vuota — il BTC nativo funziona invece con il proprio modello wallet: crea un wallet protetto da password con POST /api/v2/bitcoin/wallets, deriva indirizzi di deposito sotto di esso, e invia con POST /api/v2/bitcoin/transactions. La documentazione di Solana copre creazione indirizzi, trasferimenti SOL e SPL, e query su saldo e blocco, ma non ancora i webhook. Per qualsiasi cosa non elencata qui, la documentazione API ha lo stato attuale.
Un esempio di blockchain API: la prima chiamata in quattro linguaggi
Ottieni una API key (sezione successiva), poi conferma che funzioni. GET /api/account restituisce i dettagli del tuo account e dimostra che la key è valida.
curl https://app.chaingateway.io/api/account \
-H "Authorization: Bearer YOUR_API_KEY"Questo è l'intero controllo di autenticazione — crea un account e la stessa chiamata dimostra che la tua key funziona.
Come ottenere una API key per la blockchain
Registrati su app.chaingateway.io/register. La prova di 7 giorni parte senza KYC.
Copia la API key dal tuo pannello.
Inviala con ogni richiesta come Authorization: Bearer YOURAPIKEY, e tienila solo lato server. Il codice lato client la esporrebbe a chiunque apra la console del browser. Il pannello account può inoltre limitare la key agli indirizzi IP dei tuoi server, così una key trapelata è inutile ovunque altro. Altri passaggi di hardening sono nei nostri consigli di sicurezza per la blockchain API.
Ricevere depositi: il flusso webhook
Un'integrazione di pagamento di solito assomiglia a questo:
Crea o importa un indirizzo di deposito per ogni cliente.
Il cliente invia monete o token a quell'indirizzo.
Una volta che il trasferimento si liquida, Chaingateway invia tramite POST una notifica al tuo callback URL — con un header X-Signature se hai impostato un secret personale.
Il tuo server verifica la firma e accredita l'account del cliente.
Sicurezza dei webhook in pratica
Un endpoint webhook è una porta verso il tuo backend, e questa porta in particolare accredita denaro. Chaingateway ti offre tre meccanismi per proteggerla; un handler di produzione dovrebbe usarli tutti e tre. Questo vale per le sei chain con webhook di deposito — il rilevamento depositi su Solana usa invece il polling, trattato più avanti.
1. Verifica la firma
Imposta un secret personale nelle impostazioni del tuo profilo — da quel momento ogni notifica porterà un header X-Signature, costruito come base64 di un HMAC-SHA256 sul campo txid del payload, con quel secret come chiave. Ricalcolalo dal txid ricevuto, confrontalo con il valore dell'header prima di accreditare qualsiasi cosa, e usa un confronto a tempo costante — la maggior parte delle librerie standard ne include uno. Rifiuta i fallimenti con un 401. Questo chiude l'attacco ovvio: chiunque scopra il tuo callback URL può inviare tramite POST depositi fabbricati verso di esso, e senza il controllo della firma il tuo negozio spedirebbe merce per pagamenti mai avvenuti.
2. Progetta per il reinvio
Una notifica può raggiungerti più di una volta — puoi reinviare quelle fallite tramite l'API, e nulla garantisce una consegna esattamente una volta nel frattempo. Basa la tua logica di accredito sull'hash di transazione invece che sul numero di callback ricevute — un INSERT ... ON CONFLICT DO NOTHING sulla colonna dell'hash costa una riga ed elimina tutta questa classe di bug da doppio accredito. Rispondi con un 2xx appena la notifica è persistita e fai l'elaborazione lenta dopo; un handler che fa lavoro pesante in linea incontra timeout e trasforma un deposito in un caso di supporto.
3. Usa le rotte di recupero
Se il tuo endpoint era offline o ha risposto con un errore, la consegna finisce nell'elenco delle fallite: GET /api/v2/{chain}/webhooks/notifications/failed mostra cosa non è arrivato, e POST /api/v2/{chain}/webhooks/notifications/{id}/retry reinvia ciascuna su tuo comando. Per tutto il resto — un failover del database, un deploy andato male, un certificato TLS scaduto — GET /api/v2/{chain}/webhooks/notifications restituisce l'intera cronologia delle consegne, così un job di riconciliazione notturno può confrontarla con la tua contabilità e riparare le lacune. I dettagli del payload e il codice di verifica sono nella guida ai webhook.
Testa su testnet, distribuisci lo stesso codice
Ogni rotta accetta un header aggiuntivo, X-Network: testnet, e viene eseguita contro la rete di test invece che su mainnet. Endpoint, corpi di richiesta e forme di risposta restano identici; le monete non hanno valore. Quest'ultima proprietà è il punto. I tuoi test di integrazione possono creare indirizzi, spostare token e ricevere webhook tutto il giorno senza toccare fondi reali.
Una configurazione pratica assomiglia a questo. Metti l'header dietro una variabile d'ambiente, così staging la invia e produzione no — nessuna differenza di codice tra i due. Dai a staging un proprio callback URL, altrimenti i depositi di test finiscono nel tuo handler webhook di produzione e confondono la contabilità. Le monete di test arrivano gratis dai faucet pubblici che ogni ecosistema gestisce; la pagina delle reti supportate nella documentazione indica la rete di test per chain — Sepolia per Ethereum, Nile per TRON, Amoy per Polygon, testnet3 per Bitcoin.
Quando il flusso funziona dall'inizio alla fine — indirizzo creato, deposito rilevato, webhook verificato, saldo accreditato — elimina l'header. Nient'altro cambia. Questa simmetria è deliberata, ed è il motivo per cui andare in produzione è una modifica di configurazione anziché un secondo progetto di integrazione.
Tre integrazioni, passo per passo
Gli elenchi di funzionalità dicono poco sullo sforzo di integrazione, quindi ecco tre costruzioni che vediamo spesso, ciascuna ridotta alle sue parti mobili.
Depositi per un negozio online
Un negozio vuole accettare USDT al checkout. Quando un cliente sceglie crypto, il tuo backend assegna un indirizzo per quell'ordine e lo mostra accanto all'importo. Da lì il webhook fa il lavoro. La notifica arriva appena il trasferimento si liquida on-chain; segna l'ordine come "pagamento rilevato" e mostralo al cliente, perché un feedback rapido è ciò che fa sentire affidabile il checkout crypto. Se la tua policy richiede maggiore profondità per importi grandi, controlla la transazione con GET /api/v2/{chain}/transactions/{txid} finché non raggiungi la tua soglia, poi segna l'ordine come pagato e avvia l'evasione.
Due casi limite decidono se questa costruzione è pronta per la produzione. Sottopagamento: i clienti a volte inviano leggermente meno della fattura, di solito perché il loro wallet ha dedotto le commissioni di rete dall'importo inserito. Decidi la tolleranza in anticipo — assorbire una piccola carenza, oppure trattenere l'ordine e richiedere la differenza. Il sovrapagamento è più raro e più semplice: accreditalo o rimborsalo, ma registralo comunque. Entrambi i casi emergono dal confrontare l'importo notificato con l'importo della fattura, invece di trattare qualsiasi callback come "pagato".
Pagamenti in batch
Una piattaforma di affiliazione paga centinaia di partner in stablecoin ogni mese, su Polygon perché lì le commissioni restano contenute rispetto agli importi dei pagamenti. La costruzione è una coda e un ciclo:
import requests
payouts = load_pending_payouts() # [{"address": ..., "amount": ...}, ...]
for p in payouts:
r = requests.post(
"https://app.chaingateway.io/api/v2/polygon/transactions/erc20",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"contractaddress": "0xTokenContract...",
"from": "0xTreasuryWallet...",
"to": p["address"],
"amount": p["amount"],
"password": "treasury-wallet-password",
},
)
record_result(p, r.json()) # persist before the next iteration
La coda conta più del ciclo. Persisti lo stato di ogni pagamento prima di inviarlo, salva subito la risposta dell'API, e non ripetere mai un invio solo perché la chiamata HTTP è andata in timeout — la transazione potrebbe comunque essere andata a buon fine. Controlla i tuoi risultati salvati e GET /api/v2/polygon/transactions, che elenca ogni transazione creata tramite l'API, e reinvia solo ciò che verificabilmente non è mai avvenuto. Questa singola regola separa i sistemi di pagamento che sopravvivono agli audit da quelli che finiscono in archeologia di fogli di calcolo.
Fatturazione on-chain per un SaaS
Uno strumento B2B fattura i clienti mensilmente in stablecoin perché i processori di carte continuano a rifiutare la sua categoria merceologica. La costruzione riutilizza il pattern del negozio con una variante: un nuovo indirizzo di deposito per fattura, non per cliente. L'indirizzo per fattura rende banale l'abbinamento — qualsiasi importo che arrivi all'indirizzo della fattura 4711 appartiene alla fattura 4711 — ed elimina l'incertezza di abbinare i pagamenti per importo quando due fatture capitano a totalizzare la stessa cifra. Il webhook segna le fatture come pagate; un job programmato fa scadere quelle vecchie e invia promemoria. Nulla in questo flusso richiede una UI wallet, un'estensione browser o qualsiasi conoscenza crypto da parte del cliente oltre alla capacità di inviare un trasferimento.
Blockchain supportate
Ogni chain ha una propria pagina con endpoint ed esempi di codice:
- Bitcoin API — la chain originale. Trasferimenti nativi BTC da wallet cifrati con password, più webhook di deposito per i pagamenti in entrata.
- Ethereum API — la piattaforma di smart contract più adottata, con trasferimenti di token ERC-20 e supporto NFT ERC-721.
- TRON API — transazioni TRC-10 e TRC-20, staking tramite freeze e delegate, e rotte self-signing build/broadcast. Stima i costi di trasferimento in anticipo con la calcolatrice delle commissioni TRON.
- Solana API — creazione indirizzi e transazioni token SPL su una chain ad alto throughput.
- BNB Smart Chain API — trasferimenti BEP-20 con lo stesso pattern di rotte usato su Ethereum.
- Polygon API — trasferimenti ERC-20 sulla chain di scaling di Ethereum, a una frazione dei costi gas di mainnet. Questa è la blockchain API di Polygon, non il servizio dati azionari di Polygon.io.
- Arbitrum API — L2 di Ethereum per alto throughput, che condivide il layout degli endpoint di mainnet.
Migrare da JSON-RPC a REST
Una blockchain API sostituisce le chiamate JSON-RPC grezze con un'unica richiesta REST autenticata per azione. Dove JSON-RPC richiede diversi round trip per trasferimento, più codifica manuale ABI, tracciamento del nonce e firma, una chiamata come POST /api/v2/{chain}/transactions/erc20 (bep20 su BNB Smart Chain) racchiude tutto ciò in un'unica richiesta.
Molti team arrivano qui con un'integrazione già in esecuzione: web3.js contro un endpoint RPC a pagamento, o un client JSON-RPC costruito a mano da un'epoca precedente della codebase. La migrazione è meno drammatica di quanto sembri, perché l'API assorbe intere categorie di codice invece di sostituirlo chiamata per chiamata.
Prendi il percorso di invio canonico EVM. Su JSON-RPC, un trasferimento di token è una sequenza: eth_getTransactionCount per il nonce, eth_gasPrice o una chiamata fee-history per il pricing, eth_estimateGas contro calldata codificata ABI, firma locale, poi eth_sendRawTransaction per trasmettere. Ogni passaggio ha modalità di errore che il tuo codice gestisce attualmente — o silenziosamente non gestisce. Tutti e cinque si condensano in un'unica POST autenticata a /api/v2/{chain}/transactions/erc20, e la contabilità del nonce, la solita fonte di ticket "transazione bloccata", esce completamente dalla tua codebase.
Il rilevamento degli eventi cambia forma più che logica. Dove facevi polling su eth_getLogs con un cursore di blocco o tenevi aperta una sottoscrizione WebSocket attraverso ogni bug di riconnessione, ora registri un webhook ed elimini il poller. La tua logica a valle — analizzare il trasferimento, abbinare il cliente, accreditare il saldo — resta com'è; solo il lato dell'input passa da pull a push.
Ciò che non si trasferisce: strumenti di consenso, indicizzatori personalizzati, qualsiasi cosa richieda accesso ai blocchi grezzi. Mantieni un endpoint RPC per quei compiti; i due coesistono senza attriti. I pagamenti sono di solito il primo carico di lavoro che vale la pena spostare, perché portano il maggior rischio operativo per riga di codice. Il confronto più esteso, inclusi i casi in cui un nodo vince, è in blockchain API vs. blockchain node.
Quando una richiesta fallisce
La gestione degli errori per un'API di pagamenti merita più di un generico blocco catch, perché una richiesta fallita e una transazione fallita sono eventi diversi.
Il livello HTTP segue le convenzioni REST. Un 401 significa che il Bearer token manca, è sbagliato o è scaduto — correggi la credenziale, non riprovare. Altre risposte nell'intervallo 4xx dicono che la richiesta stessa è colpevole: un indirizzo malformato, un campo mancante, un errore di validazione. Registra il corpo della risposta, che indica il problema specifico, e tratta questi come bug da correggere piuttosto che condizioni transitorie da ritentare. L'intervallo 5xx e i timeout a livello di rete formano la classe transitoria, dove un retry con backoff esponenziale è il riflesso giusto.
Con un'eccezione, ed è quella che conta. Non ritentare mai alla cieca una richiesta che sposta fondi. Un timeout ti dice che non hai ricevuto la risposta — non che la transazione sia fallita. La sequenza sicura: controlla se il trasferimento è uscito, usando i tuoi risultati salvati e GET /api/v2/{chain}/transactions (l'elenco delle transazioni create dalla tua key), e reinvia solo quando puoi dimostrare che non è mai avvenuto. Le chiavi di idempotenza dal tuo lato, legate ai tuoi ID di pagamento o ordine, rendono economico quel controllo.
Costruisci l'osservabilità fin dal primo giorno. Registra le coppie richiesta-risposta per ogni chiamata che sposta denaro, e allertati sui tassi di 4xx oltre che solo sui 5xx — un'impennata improvvisa di errori di validazione di solito significa che un deploy ha rotto il formato della tua richiesta. Coglierlo in pochi minuti invece che in giorni è la differenza tra un incidente e una nota a margine.
Gestire i propri nodi o usare un'API?
Gestire i nodi da soli ti dà controllo totale e nessuna dipendenza da terzi. Significa anche una macchina per chain, budget di disco e banda, monitoraggio della sincronizzazione e aggiornamenti di versione — moltiplicato per sette se vuoi la copertura descritta sopra. Il nostro confronto di blockchain API vs. blockchain node illustra quel compromesso. La versione breve: gestisci un nodo quando ti serve controllo a livello di consenso, usa l'API quando ti servono pagamenti funzionanti questa settimana.
Domande frequenti
Pronto ad accettare pagamenti crypto?
Crea un account su app.chaingateway.io/register, scegli una chain tra le sette sopra e invia un trasferimento testnet. Il riferimento completo degli endpoint è nella documentazione, e piani e rate limit hanno una pagina propria.