Bitcoin API: accetta pagamenti BTC senza gestire un node

Il JSON-RPC di Bitcoin Core vuole un nodo sincronizzato prima della prima risposta utile. Una REST API vuole una API key. La differenza si vede nel tuo calendario: il download iniziale dei blocchi richiede giorni su hardware tipico, e dopo il nodo consuma disco e banda, e continua a richiedere monitoraggio, per tutta la vita del tuo prodotto. Il nostro articolo su blockchain API vs. blockchain node confronta i due approcci in dettaglio. Gestisci un tuo nodo quando hai bisogno di un controllo a livello di policy sulla tua visione della rete; usa l'API quando l'obiettivo sono i pagamenti.

Le chiamate quotidiane si adattano perfettamente al modello REST. Dove un'integrazione a nodo avvolge getnewaddress e listtransactions e fa polling per i cambiamenti, l'API assegna indirizzi e lascia che sia il webhook a sorvegliare. I cicli di polling scompaiono, e con loro i cron job che si rompono silenziosamente durante un weekend.

C'è una seconda differenza. I metodi RPC grezzi restituiscono dati grezzi. Chaingateway restituisce JSON strutturato con campi leggibili, così una risposta può finire direttamente nel tuo database invece che passare per un livello di parsing.

Il lato REST del percorso di invio sono tre endpoint. POST /api/v2/bitcoin/wallets crea un wallet, cifrato con una password che Chaingateway non memorizza — perdila e nessuno può ripristinare il wallet, ed è proprio questo il punto. POST /api/v2/bitcoin/wallets/{wallet}/addresses deriva tutti gli indirizzi che ti servono sotto di esso; un wallet li porta tutti. E POST /api/v2/bitcoin/transactions invia:

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

La risposta porta il txid della transazione trasmessa. speed accetta fast, medium o slow e imposta il livello di commissione — il compromesso tra costo e tempo alla prima conferma. Un subtractfee: true opzionale deduce la commissione di rete dall'importo invece di aggiungerla sopra, il che è ciò che vuoi quando un cliente preleva l'intero saldo.

Bitcoin aggiunge un blocco circa ogni dieci minuti, sebbene gli intervalli singoli varino molto. Ogni nuovo blocco minato sopra quello che contiene la tua transazione aggiunge una conferma, e ogni conferma rende più difficile l'inversione.

Sei conferme — circa un'ora — è stato lo standard de facto per "liquidato" fin dai primi giorni degli exchange, e resta valido a metà 2026.

Dieci minuti sono una media, non un orario

L'aggiustamento della difficoltà lo mantiene nel tempo, ma gli intervalli singoli si disperdono ampiamente attorno ad esso — due blocchi in un minuto capitano, e così pure siccità di quaranta minuti. L'esperienza utente nei pagamenti deve rispettare questo: "circa dieci minuti" è una media, non una promessa, quindi la tua pagina di checkout dovrebbe dire "di solito entro un'ora" invece di far girare un conto alla rovescia che non può mantenere.

Perché non accreditare a zero conferme?

Perché finché una transazione non è in un blocco, resta nel mempool, dove può essere sostituita o doppiamente spesa, e anche il blocco più recente può uscire dalla chain in una riorganizzazione. L'API divide quel lavoro in due. Il webhook scatta una volta che la transazione si liquida on-chain — il payload porta importo, indirizzo, txid e numero di blocco — così la tua UI può reagire subito. Da lì, GET /api/v2/bitcoin/transactions/{txid}/decoded restituisce il conteggio attuale delle conferme, così il tuo libro contabile accredita solo denaro che ha raggiunto la tua soglia. Mostra il progresso presto, liquida tardi.

Bitcoin non ha saldi di account. Ciò che la chain memorizza sono unspent transaction output — UTXO — ciascuno un blocco discreto di valore vincolato a un indirizzo. Il "saldo" di un wallet è un numero che il tuo software deriva sommando ogni UTXO controllato dai suoi indirizzi; il protocollo non memorizza mai quella somma da nessuna parte. Spendere consuma UTXO interi e ne crea di nuovi, incluso un output di resto verso te stesso, nello stesso modo in cui pagare un conto da 7 euro con una banconota da 10 restituisce monete.

Ethereum funziona con il modello opposto. Un account ha un saldo, la chain lo memorizza direttamente, e un deposito è un incremento. Sulle chain EVM è normale dare a un cliente un unico indirizzo e lasciare che vi si accumulino cento depositi nel corso degli anni.

Per la gestione dei depositi, il modello UTXO ha un vantaggio pratico: ti spinge verso un indirizzo per cliente o per fattura, che è comunque il design più pulito. Ogni pagamento in entrata è un nuovo output verso un indirizzo che osservi, quindi l'attribuzione è inequivocabile — nessun parsing di memo, nessun abbinamento per importo. Significa anche che "il saldo di un indirizzo" è una domanda a cui risponde un indexer piuttosto che la chain, che è esattamente la contabilità che esternalizzi usando un'API con webhook invece di gestire tu stesso la macchina. La notifica ti dice: questo importo, questo indirizzo, questa transazione, questo blocco. Il resto lo fa il tuo libro contabile.

Aggiungi l'header X-Network: testnet e ogni chiamata di questa pagina gira sulla rete di test di Bitcoin: stesse rotte, stesse forme di risposta, monete senza valore. I faucet distribuiscono BTC di test gratuitamente, quindi l'intero flusso di deposito — indirizzo, pagamento, webhook, conferme — può essere provato dall'inizio alla fine senza spendere un satoshi.

Tieni l'header dietro la configurazione anziché sparso nel codice, e dai al tuo ambiente di staging un callback URL separato così i depositi di test non possono finire nel libro contabile di produzione. Quando la prova funziona, rimuovi l'header. Nient'altro dell'integrazione cambia, ed è questo il punto: il primo deposito su mainnet dovrebbe essere noioso.

Un backend di pagamenti si guadagna la fiducia nei giorni difficili, quindi pianifica esplicitamente i percorsi di fallimento.

Sul livello HTTP le regole sono quelle standard di REST. Un 401 significa che il Bearer token è sbagliato o mancante; correggi la key invece di ritentare. Altre risposte 4xx puntano alla richiesta stessa — registra il corpo, che indica il problema, e trattalo come un bug. Le risposte nell'intervallo 5xx e i timeout sono transitori; ritenta quelli con backoff.

Le modalità di fallimento specifiche di Bitcoin vivono sopra HTTP. Un deposito che non conferma mai di solito ha pagato troppo poca commissione ed è bloccato nel mempool; potrebbe confermare ore dopo o sparire del tutto, motivo per cui detected e settled devono restare stati separati nel tuo sistema. Una notifica per un importo inferiore alla fattura è una decisione di business, non un errore — gestiscila nel codice, non in una coda di supporto. E se il tuo endpoint webhook era offline, le consegne fallite ti aspettano: GET /api/v2/bitcoin/webhooks/notifications/failed le elenca, POST /api/v2/bitcoin/webhooks/notifications/{id}/retry reinvia ciascuna, e l'elenco completo su GET /api/v2/bitcoin/webhooks/notifications ti permette di confrontarlo con il libro contabile e accreditare le lacune. Esegui quel confronto ogni notte anche quando nulla sembra sbagliato. Una riconciliazione che gira solo dopo gli incidenti trova i suoi bug in produzione.

Bitcoin stesso non ha USDT o USDC — le stablecoin vivono su altre chain. Ciò che la piattaforma condivisa ti offre è un vantaggio di partenza: la tua integrazione Bitcoin parla già la stessa API dei nostri endpoint Ethereum e TRON. Accetta BTC oggi, aggiungi USDT su TRON nello sprint successivo con la stessa key e lo stesso handler webhook. La panoramica della blockchain API elenca tutte e sette le chain supportate.

L'ordine pratico per la maggior parte dei team: lancia prima i depositi BTC, perché è ciò che i clienti chiedono per nome, poi lascia che i dati di pagamento ti dicano quale binario di stablecoin aggiungere per secondo. Su Chaingateway, quel secondo binario riutilizza invariati la tua verifica della firma, il tuo job di riconciliazione e la tua macchina a stati dei depositi.

• Ha il track record più lungo di qualsiasi blockchain, in funzione dal 2009, e il maggiore riconoscimento tra gli utenti finali.
• La rete si liquida 24 ore su 24. Non ci sono orari bancari né chiusure regionali.
• Le conferme seguono un ritmo prevedibile, con un nuovo blocco circa ogni dieci minuti, il che mantiene facilmente ragionabili i flussi di pagamento.
• L'adozione è la più ampia di tutte le reti crypto, quindi "accettate Bitcoin?" resta la prima domanda che fanno i clienti.

Nessuna di queste proprietà è arrivata da un aggiornamento di roadmap; sono le stesse garanzie con cui la rete è stata lanciata. Quella stabilità è l'argomento a favore di BTC nei prodotti con orizzonti lunghi: un'integrazione costruita quest'anno non diventerà obsoleta per un cambio di rotta del protocollo l'anno prossimo, il che è più di quanto possa dire la maggior parte degli stack di pagamento.

Il caso ovvio è il checkout: un cliente sceglie Bitcoin e la tua app assegna un indirizzo; il webhook conferma il pagamento. Gli stessi blocchi costruttivi sostengono anche carichi più pesanti. Exchange e piattaforme di gaming gestiscono un indirizzo di deposito per utente e accreditano i saldi alla conferma. I flussi di payout e rimessa spingono trasferimenti transfrontalieri senza banche corrispondenti nel mezzo. Le attività in abbonamento generano un nuovo indirizzo di fattura a ogni ciclo e lasciano che il webhook lo chiuda.

Ciò che questi casi condividono è la forma del lavoro. Bitcoin gestisce la liquidazione; la tua applicazione gestisce lo stato. L'API si colloca tra i due e trasforma gli eventi on-chain in chiamate HTTP che il tuo framework già sa instradare — motivo per cui il caso del checkout e quello dell'exchange girano sulla stessa manciata di endpoint.