Solana API: pagamenti SOL e token SPL via REST

La via ufficiale verso Solana è JSON-RPC, documentata su solana.com/docs/rpc. Espone il protocollo del nodo: metodi come getLatestBlockhash e sendTransaction, più una libreria client per renderli utilizzabili. Per inviare un token SPL in quel modo, il tuo codice recupera un blockhash recente prima che scada, risolve l'associated token account del destinatario (creandolo se non esiste ancora), poi costruisce, firma e serializza la transazione. In JavaScript, web3.js e il pacchetto spl-token fanno questo per te. In ogni altro linguaggio, sei in gran parte da solo.

Chaingateway sostituisce tutto ciò con un'unica chiamata HTTP. L'API risolve i token account e costruisce la transazione lato server, e il tuo backend non importa mai un SDK Solana. Se vuoi accesso grezzo alla chain per analytics o programmi personalizzati, un provider RPC è lo strumento giusto. Per i pagamenti, REST è più breve, e il codice più breve ha meno posti dove rompersi.

Se vieni da Ethereum, BSC o Polygon, la parte di Solana che più probabilmente ti coglierà di sorpresa non è la velocità o le commissioni. È il modello degli account.

Il modello EVM

Un saldo di token è una voce all'interno dello storage proprio del contratto del token. Il tuo indirizzo "possiede" USDT perché la tabella interna del contratto lo dice. Inviare token a un wallet completamente nuovo aggiunge solo una riga a quella tabella; il destinatario non deve esistere on-chain in alcun modo speciale.

Il modello Solana

Solana divide la stessa idea in account separati. Un token è definito dal suo mint account, che memorizza supply e decimali. I saldi vivono in token account, uno per ogni combinazione di wallet e mint, e la variante standard è l'associated token account (ATA): il suo indirizzo è derivato in modo deterministico dall'indirizzo del wallet e dall'indirizzo del mint. Il tuo wallet non contiene USDC. Possiede un account separato che contiene USDC.

Due conseguenze per i pagamenti

1. Un ATA deve esistere prima che i token possano arrivarvi. Se il tuo destinatario non ha mai posseduto il token, l'account deve essere creato on-chain, e la creazione richiede un deposito per renderlo rent-exempt: 0,00203928 SOL a metà 2026, secondo la documentazione ufficiale di Solana. In pratica la transazione del mittente crea e finanzia l'account mancante.
2. I trasferimenti spostano valore tra token account, non tra indirizzi wallet. Il codice che punta ingenuamente all'indirizzo wallet fallisce, motivo per cui l'istruzione di trasferimento SPL richiede entrambi i token account più il mint e i suoi decimali per la verifica.

Questa contabilità è esattamente ciò che Chaingateway fa lato server. Tu passi indirizzi wallet e un token mint; l'API deriva i token account e costruisce un trasferimento valido. Il tuo backend non impara mai cos'è un program-derived address, ed è proprio questo il punto.

I numeri sotto sono verificati sulla documentazione ufficiale di Solana a inizio luglio 2026.

Uno slot, la finestra in cui un validatore può produrre un blocco, è configurato a circa 400 millisecondi e oscilla tra circa 400 e 600 millisecondi nella pratica. Questa cadenza è il motivo per cui il polling dei depositi ogni uno o due secondi non resta mai troppo indietro rispetto alla chain.

La commissione base di transazione è di 5.000 lamport per firma, pari a 0,000005 SOL. Metà viene bruciata, metà va al produttore del blocco. Sopra di essa c'è una commissione di priorità opzionale, prezzata in micro-lamport per unità di calcolo; per default è zero e compra preferenza di scheduling quando la rete è occupata. Per un carico di lavoro di pagamento la lettura pratica è semplice: le commissioni sono così piccole da scomparire nel tuo margine anche su una transazione da un dollaro.

Conferma e finalità sono cose diverse su Solana, e la distinzione conta per come accrediti i depositi. Una transazione è tipicamente confermata, cioè una supermaggioranza di validatori ha votato sul suo blocco, entro un secondo o due. La finalità completa richiede circa 12,8 secondi a metà 2026. L'upgrade di consenso Alpenglow, previsto per fine 2026, punta a comprimere la finalità a circa 100-150 millisecondi; trattalo come un piano annunciato piuttosto che una proprietà già attiva finché non viene rilasciato. Una policy sensata oggi: accredita i pagamenti piccoli alla conferma, trattieni quelli grandi per quella dozzina di secondi extra fino alla finalità.

Solana non ha ancora un endpoint webhook di deposito sull'API di Chaingateway. Il rilevamento fa invece polling su due chiamate: GET /api/v2/solana/blocks/number per tracciare i nuovi blocchi e GET /api/v2/solana/balances/{address} per verificare fondi in arrivo. Con slot sotto il secondo, un intervallo di polling di due secondi mostra comunque un pagamento come ricevuto entro pochi secondi.

Un ciclo di polling disciplinato è economico da eseguire. Memorizza l'altezza di blocco elaborata l'ultima volta, e ogni volta che avanza, controlla i tuoi indirizzi di deposito — o GET /api/v2/solana/balances/{address}/tokens/{mint} per un token SPL specifico — e confronta ciò che trovi con gli ordini aperti.

Il costo di latenza è inferiore a quanto sembri. Solana produce blocchi in meno di un secondo, quindi anche un intervallo di polling di due secondi significa che un cliente vede "pagato" entro pochi secondi dall'invio. L'intero ciclo è poche decine di righe in qualsiasi linguaggio e gira come un cron job o un worker in background. Quando in seguito estendi lo stesso flusso a una chain con webhook, la contabilità resta identica; cambia solo il trigger, da pull a push.

USDC è il canale di pagamento che ha reso Solana una rete di liquidazione, quindi merita un percorso concreto. L'indirizzo mint su mainnet è EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, emesso da Circle; qualsiasi altra cosa che dichiari di essere USDC non lo è.

Il lato ricevente: quando un cliente effettua il checkout, crea un nuovo indirizzo con POST /api/v2/solana/addresses e memorizzalo insieme all'ordine. Mostra l'indirizzo e l'importo, e lascia che il cliente paghi da qualsiasi wallet o exchange. Il tuo ciclo di polling della sezione precedente rileva il trasferimento in entrata, abbina l'indirizzo ricevente all'ordine, e lo segna come pagato. Con slot da 400 millisecondi, il divario tra "il cliente ha premuto invia" e "il tuo database dice pagato" è di pochi secondi, per lo più il tuo stesso intervallo di polling.

Registra la firma di transazione di ogni deposito accreditato con un vincolo di unicità. I cicli di polling vengono riavviati, riempiti retroattivamente ed eseguiti di nuovo, e l'idempotenza a livello di database fa sì che nulla di tutto ciò possa accreditare un ordine due volte.

Il lato pagante lo rispecchia. Un pagamento è una singola chiamata POST /api/v2/solana/transactions/SPL con il mint USDC come contractaddress e un "amount": 10 leggibile; l'API applica per te i sei decimali di USDC. Mantieni un saldo SOL modesto sull'indirizzo mittente: 0,000005 SOL per firma per le commissioni, più 0,00203928 SOL ogni volta che va creato il token account di un destinatario. Entrambi gli importi sono abbastanza piccoli che un unico saldo ricaricato copre mesi di pagamenti.

Ciò che ottieni rispetto ai circuiti carta è la liquidazione in secondi senza meccanismo di chargeback, e ciò a cui rinunci è la capacità di annullare un errore. La validazione degli indirizzi che l'API esegue prima di costruire una transazione è tua alleata qui, ma conta altrettanto la tua stessa schermata di conferma.

SPL è lo standard token di Solana, e l'API tratta ogni mint SPL allo stesso modo. USDC e USDT funzionano immediatamente, con i decimali applicati automaticamente. Se hai coniato un tuo token, passa il suo mint address allo stesso endpoint e si comporta come i principali. Poiché Chaingateway usa un'unica struttura di endpoint tra le chain, il codice Solana sopra si trasferisce a Ethereum, BSC o Polygon scambiando il segmento chain e il suffisso token nell'URL: /solana/transactions/SPL diventa /ethereum/transactions/erc20.

Solana esegue le transazioni in parallelo anziché rigorosamente una dopo l'altra, ed è da lì che deriva il suo throughput. Le commissioni sono abbastanza piccole da rendere economico pagare importi minimi, e la conferma è abbastanza veloce da permettere a una pagina di checkout di semplicemente aspettarla. Il volume USDC su Solana ha trasformato la chain in una seria rete di liquidazione, e lo slancio degli sviluppatori attorno a essa ha retto attraverso diversi cicli di mercato.

Solana gestisce due cluster di test pubblici, e i nomi confondono le persone. Devnet è il sandbox quotidiano per gli sviluppatori di applicazioni: SOL gratuito è disponibile tramite airdrop da faucet, e nulla su di esso ha valore. Testnet esiste principalmente perché validatori e contributor principali esercitino nuove release sotto carico. Se hai usato Sepolia di Ethereum, devnet è l'equivalente più vicino nello spirito.

Con Chaingateway non gestisci affatto URL di cluster. Aggiungi l'header X-Network: testnet a qualsiasi richiesta e viene eseguita contro l'ambiente di test; rimuovilo e la richiesta identica è una chiamata mainnet. Non c'è una seconda API key né un account separato.

Usa l'esecuzione di test per gli scenari che fanno male su mainnet: un pagamento verso un indirizzo che non ha mai posseduto il token (il percorso di creazione token account), un riavvio del tuo ciclo di polling a metà, e un invio duplicato dello stesso pagamento. Ciascuno di questi richiede minuti per essere provato e ciascuno è un incidente reale se lo incontri per la prima volta in produzione.

L'API riporta i problemi come semplici codici di stato HTTP, quindi nulla della tua gestione degli errori deve essere specifico di Solana.

Un 401 significa che il Bearer token manca o è sbagliato. Gli errori nell'intervallo 4xx sono fallimenti di validazione, come un indirizzo che non si decodifica come base58 o un campo mancante; il corpo JSON dice cosa correggere, e ritentare senza cambiare il payload è inutile. Un 429 significa che hai raggiunto il rate limit del tuo piano; rallenta, e calibra il polling dei depositi sul battito dell'altezza di blocco anziché su un ciclo serrato. I piani con limiti più alti sono nella pagina prezzi.

Gli errori server nell'intervallo 5xx sono sicuri da ritentare per le letture. Per gli invii di token, sii più cauto: dopo un timeout non sai se il trasferimento è stato trasmesso, e Solana qui non ha ancora una traccia webhook. Controlla i tuoi record e i trasferimenti recenti dell'indirizzo prima di inviare di nuovo, e mantieni una riga di database per ogni pagamento previsto così che una riesecuzione del tuo worker non possa inviare due volte.

Registra il corpo completo della risposta accanto alla tua richiesta. I codici di stato e gli schemi di errore per endpoint sono nella documentazione API.

Il pattern più comune è l'accettazione di pagamenti: assegna a ogni cliente un indirizzo di deposito, fai polling dei trasferimenti SPL in entrata e segna l'ordine come pagato, con liquidazione in secondi e commissioni troppo piccole per contare nel calcolo del margine. Il secondo pattern sono le operazioni wallet: piattaforme che gestiscono depositi e prelievi per molti utenti attraverso la stessa manciata di endpoint.

Gli stessi blocchi costruttivi gestiscono l'automazione dei pagamenti per airdrop e lanci di token, trasferimenti ricorrenti per la fatturazione di abbonamenti, e pagamenti transfrontalieri dove l'alternativa è una catena di banche corrispondenti che richiede giorni e trattiene punti percentuali.