← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

Integrazione multi-blockchain con un'API REST

Come integrare più blockchain con un'unica API REST: reti, endpoint dei token per catena, flusso di deposito e prelievo e le differenze che restano.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

L’integrazione multi-blockchain significa che un unico backend parla con più catene attraverso un’unica interfaccia, invece di una libreria client per ciascuna catena. Con Chaingateway Lei chiama endpoint REST con un bearer token. Lo stesso schema copre Ethereum, BNB Smart Chain, Polygon, Arbitrum, Tron, Bitcoin e Solana, entro i limiti che ogni catena impone.

Quali blockchain e standard di token copre l’API?

L’API copre sette catene, ciascuna con una testnet. Passi alla testnet con l’header X-Network: testnet. La pagina delle reti supportate elenca le reti di test. I trasferimenti di token hanno un endpoint per catena:

CatenaEndpoint di token e NFT nel file OpenAPITestnet
Ethereumtransactions/erc20, transactions/erc721Sepolia
BNB Smart Chaintransactions/bep20, transactions/bep721BSC testnet
Polygontransactions/erc20, transactions/erc721Amoy
Arbitrumtransactions/erc20, transactions/erc721Arbitrum Sepolia
Trontransactions/trc20, transactions/trc721, transactions/trc10Nile
Solanatransactions/SPLDevnet
Bitcointransactions (solo moneta nativa)Testnet3

Ogni percorso inizia con /api/v2/<chain>/. L’elenco completo è nel file OpenAPI.

Come si costruisce su di essa un servizio di deposito e prelievo?

Un flusso in stile custodial ha tre parti: un indirizzo per cliente, un webhook per ciascun indirizzo e una chiamata di prelievo. Ogni parte è una sola richiesta, e ha la stessa forma su ogni catena che la supporta.

  1. Crei un indirizzo di deposito. Sulle catene EVM e su Tron è POST /api/v2/<chain>/addresses, e la risposta contiene l’indirizzo. Passi una password così la chiave viene conservata cifrata. Senza password, la risposta contiene la chiave privata e dovrà conservarla Lei.
  2. Registri un webhook per l’indirizzo. POST /api/v2/<chain>/webhooks accetta l’url del ricevitore, l’indirizzo in to, un type come ERC20 o TRC20, e facoltativamente un contractaddress e un reference fino a 255 caratteri.
  3. Esegua il pagamento in uscita. Un prelievo di token ERC20 è una sola richiesta:
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"
}'

Su BNB Smart Chain sostituisca ethereum/transactions/erc20 con bsc/transactions/bep20. Su Tron usi tron/transactions/trc20, che accetta gli stessi campi tranne le impostazioni del gas. Solana è diversa: solana/transactions/SPL richiede la privatekey del mittente e non accetta una password del wallet. L’articolo sui segreti personali spiega come verificare le notifiche che riceve.

Che cosa succede quando una richiesta fallisce?

L’API restituisce un corpo JSON con status, ok e message. Un 401 con il messaggio «Wrong password provided» significa che la password del wallet non corrisponde. Un 422 riporta l’errore del nodo stesso, per esempio insufficient funds for gas * price + value. La parte specifica della catena è la causa: un trasferimento ERC20 su Ethereum richiede ETH per il gas sull’indirizzo mittente, e un trasferimento TRC20 richiede energy e bandwidth oppure TRX da bruciare. Verifichi i saldi prima di riprovare, perché un nuovo tentativo non risolve una commissione mancante.

Le notifiche webhook fallite non vengono reinviate automaticamente. Le elenca con GET /api/v2/<chain>/webhooks/notifications/failed e ne reinvia ciascuna con l’endpoint di retry. Una notifica reinviata può arrivare dopo le altre, quindi renda il ricevitore idempotente su txid.

Che cosa resta diverso tra le catene?

Restano diverse alcune cose, e l’API non le nasconde:

  • Commissioni: Ethereum, BNB Smart Chain, Polygon e Arbitrum usano il gas, con un endpoint gasprice per ciascuna. Tron usa energy e bandwidth.
  • Webhook: tutte le catene tranne Solana.
  • Wallet: Bitcoin funziona con wallet con nome che contengono più indirizzi, creati con POST /api/v2/bitcoin/wallets.
  • Asset: lo stesso token su due catene sono due asset separati, e l’API non fa da ponte tra di loro.

Da quale catena conviene partire?

Parta dalla catena che i Suoi clienti già usano, e aggiunga le altre riusando gli stessi gestori. I moduli di prelievo degli exchange indicano la rete, per esempio ERC-20, BEP-20 o TRC-20. Chieda ai primi clienti su quale rete detengono USDT prima di costruire la seconda integrazione.

Che cosa conviene memorizzare per ciascuna catena?

Un servizio multi-catena deve avere la catena in ogni record, perché la stessa stringa può essere valida su più catene. Conservi almeno questi campi:

CampoPerché serve
chain e networkGli indirizzi 0x sono validi su Ethereum, BNB Smart Chain, Polygon e Arbitrum, e mainnet e testnet si assomigliano
address nel formato proprio della catenaTron usa indirizzi Base58 che iniziano con T, e la forma esadecimale con prefisso 41 compare nei dati grezzi dei nodi
contractaddress e typeLo stesso token ha un contratto diverso su ogni catena
txidLa chiave per deduplicare le notifiche webhook e per le ricerche
referenceL’ID del Suo ordine o cliente, impostato alla registrazione del webhook
Importo nell’unità base della catenaI decimali differiscono per token, quindi converta solo nel livello di visualizzazione

Aggiunga un vincolo di unicità su (chain, network, txid). Riconcili con una seconda fonte a intervalli regolari, per esempio l’elenco delle notifiche fallite e un block explorer.

Come si comincia?

Parta dalle testnet. Crei un indirizzo su Sepolia e uno su Nile, registri un webhook per ciascuno, invii un trasferimento di prova e verifichi che il Suo ricevitore gestisca entrambe le notifiche. La prova gratuita di 7 giorni non richiede carta né KYC.

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.

C
Chaingateway Team
Esperti di blockchain

Il team di Chaingateway si impegna a semplificare l'integrazione blockchain per sviluppatori di tutto il mondo.