← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

API BNB Smart Chain: che cosa si può costruire

Che cosa offre un'API BNB Smart Chain (BSC): wallet, trasferimenti BNB e BEP-20, saldi e webhook, con esempi di richieste e i limiti dell'RPC pubblico.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

Un’API BNB Smart Chain è un’interfaccia web per la BNB Smart Chain (BSC), in precedenza Binance Smart Chain. Permette a un’applicazione di creare wallet, inviare BNB e token BEP-20, leggere i saldi e ricevere notifiche di deposito senza eseguire un nodo BSC. Il backend invia richieste HTTPS, e il fornitore gestisce firma, trasmissione e accesso alla chain.

Questo articolo elenca ciò che copre un’API di questo tipo, mostra due richieste verso gli endpoint BSC di Chaingateway e spiega quando bastano gli endpoint RPC pubblici.

Che cosa copre un’API BSC?

Un’API BSC copre le operazioni di cui ha bisogno un backend di pagamento o di wallet. Gli endpoint di Chaingateway, elencati nel file OpenAPI, rientrano in cinque gruppi:

GruppoEndpoint
IndirizziPOST /api/v2/bsc/addresses crea un wallet, GET elenca i wallet, POST /api/v2/bsc/addresses/import importa una chiave privata
SaldiGET /api/v2/bsc/balances/{address} per BNB, GET /api/v2/bsc/balances/{address}/bep20/{contract_address} per un token BEP-20
TrasferimentiPOST /api/v2/bsc/transactions per BNB, POST /api/v2/bsc/transactions/bep20 per token BEP-20, POST /api/v2/bsc/transactions/bep721 per NFT
Dati della chainUltimo blocco, blocco per numero o hash, transazione, ricevuta, prezzo del gas, proprietario di un NFT e token URI
WebhookCreazione, modifica ed eliminazione di webhook, elenco delle notifiche, elenco delle notifiche fallite e nuovo invio

Tutte le richieste usano un bearer token nell’header Authorization. Con X-Network: testnet si usa la rete di test. Senza l’header, la richiesta va alla mainnet.

Come si verifica un saldo e si invia BNB?

Per verificare il saldo basta una richiesta GET, poi si invia BNB con una richiesta POST. Entrambi gli esempi usano l’URL di base https://app.chaingateway.io e un token preso dalla dashboard.

Terminal window
curl https://app.chaingateway.io/api/v2/bsc/balances/0x0000000000000000000000000000000000001000 \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
-H "X-Network: testnet"

La risposta contiene il saldo come stringa decimale:

{"status": 200, "ok": true, "message": "Balance fetched", "data": "0.000000000000000000"}

Per inviare BNB da un wallet creato con l’API, si inviano mittente, destinatario, importo e password del wallet. I campi del gas sono facoltativi.

Terminal window
curl -X POST https://app.chaingateway.io/api/v2/bsc/transactions \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
-H "X-Network: testnet" \
-H "Content-Type: application/json" \
-d '{"from": "0x...", "to": "0x...", "amount": "0.001", "password": "wallet-password"}'

Se il mittente ha troppo poco BNB per l’importo più il gas, l’API restituisce lo status 422 con il messaggio insufficient funds del nodo. Una password del wallet errata restituisce 401.

Come si legge il saldo di un token e una transazione?

Il saldo di un token BEP-20 si legge con l’indirizzo del wallet e l’indirizzo del contratto del token nel percorso. Una transazione si legge con il suo hash. Entrambe sono richieste GET con gli stessi header di sopra.

Terminal window
# BEP-20 token balance
curl https://app.chaingateway.io/api/v2/bsc/balances/0xWalletAddress/bep20/0xTokenContract \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN"
# Transaction with decoded data
curl https://app.chaingateway.io/api/v2/bsc/transactions/0xTransactionHash/decoded \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN"
# Current gas price
curl https://app.chaingateway.io/api/v2/bsc/gasprice \
-H "Authorization: Bearer $CHAINGATEWAY_TOKEN"

L’endpoint del saldo restituisce l’importo del token come stringa decimale, quindi non serve scalarlo manualmente in base ai decimali del token. L’endpoint della transazione decodificata restituisce una transazione in campi leggibili invece che in dati esadecimali grezzi. Un hash sconosciuto restituisce una risposta 422 con il messaggio transaction not found.

GET /api/v2/bsc/transactions elenca la cronologia delle transazioni dell’account. Elenca solo le transazioni fatte tramite l’API di Chaingateway, perché Chaingateway non indicizza da sola gli indirizzi. Per vedere i trasferimenti in entrata si usa un webhook.

Se si possiede già un wallet, POST /api/v2/bsc/addresses/import importa la sua chiave privata. I wallet importati e quelli nuovi usano gli stessi endpoint di invio e webhook.

Come si ricevono notifiche sui depositi?

Un webhook si crea con POST /api/v2/bsc/webhooks. Il campo url è obbligatorio. Si filtra per to (un indirizzo ricevente), per from oppure per contractaddress nel caso di un token, e si imposta type su BNB, BEP20 o BEP721. Quando viene rilevata una transazione corrispondente, Chaingateway invia i dati della transazione all’URL indicato.

I webhook non vengono ripetuti automaticamente. Una consegna fallita compare in GET /api/v2/bsc/webhooks/notifications/failed, e POST /api/v2/bsc/webhooks/notifications/{id}/retry la invia di nuovo. L’endpoint di ricezione deve essere idempotente, con chiave sull’ID della transazione, così che un nuovo invio non accrediti un conto due volte.

Che cos’è BEP-20?

BEP-20 è lo standard dei token della BNB Smart Chain. Secondo la sua specifica, deriva dall’ERC-20 di Ethereum e richiede le funzioni symbol(), decimals(), totalSupply(), balanceOf(), transfer(), transferFrom(), approve() e allowance(). Per questo lo stesso codice di wallet funziona per i token su BSC e su Ethereum, ed è anche il motivo per cui gli endpoint BSC di Chaingateway riflettono quelli di Ethereum.

Quando bastano gli endpoint RPC pubblici?

La BNB Chain pubblica endpoint JSON-RPC pubblici per mainnet e testnet. La documentazione della BNB Chain indica un limite di 10.000 richieste ogni 5 minuti e precisa che eth_getLogs è disattivato sugli endpoint pubblici della mainnet.

Per prototipi e letture occasionali questo basta. Per un servizio che controlla molti indirizzi servono un nodo proprio, un fornitore oppure un’API che invii gli eventi. Per la strada del nodo, consultate come comunicare con un nodo tramite JSON-RPC. Ulteriori informazioni dal lato Chaingateway si trovano nella pagina dell’API BSC.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta API Binance Smart Chain 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.