Polygon Blockchain API: pagamenti in stablecoin a basso gas

La coincidenza di nomi merita altri due paragrafi, perché metà dei risultati di ricerca per "polygon api" punta al prodotto sbagliato. Polygon.io è un'azienda statunitense che vende feed di dati di mercato: quotazioni azionarie, catene di opzioni, candele forex. La sua API risponde a domande come "a quanto ha scambiato AAPL ieri". Non ha blockchain, né token, né alcuna connessione con la rete trattata in questa pagina.

Polygon la blockchain, gestita da Polygon Labs, è una rete proof-of-stake EVM-compatibile che liquida transazioni di token. La sua superficie API, sia JSON-RPC grezzo sia un livello di pagamenti come Chaingateway, risponde a domande come "l'USDC del cliente è arrivato" ed esegue istruzioni come "paga 50 USDT". Se ti servono ticker e candele OHLC, chiudi questa scheda e cerca Polygon.io. Se ti serve spostare stablecoin con commissioni gas misurate in frazioni di centesimo, continua a leggere.

La cosa più comune costruita sugli endpoint Polygon di Chaingateway è l'elaborazione di pagamenti in stablecoin, e l'economia spiega perché. Ogni trasferimento ERC-20 richiede gas. Su Ethereum mainnet, il gas per un trasferimento USDT può costare più del piccolo pagamento stesso; su Polygon, lo stesso trasferimento costa al massimo pochi centesimi. Far pagare a qualcuno 2 USDC per un prodotto digitale è praticabile qui. Su L1 non lo è.

I numeri lo confermano. A metà 2026, i tracker delle commissioni collocano un tipico trasferimento USDT su Polygon PoS tra un decimo di centesimo e due centesimi, e raramente supera qualche centesimo anche quando la rete è occupata. Lo stesso trasferimento su Ethereum mainnet è variato da ben meno di un dollaro nelle settimane tranquille a diversi dollari durante i picchi di congestione. Il divario si muove con i mercati del gas, ma si è mantenuto su due-tre ordini di grandezza per anni, e per un modello di business basato su piccoli pagamenti quel divario è l'intero business case.

Un checkout tipico appare così: il tuo backend assegna al cliente un indirizzo di deposito e mostra un codice QR, e il cliente invia USDC o USDT da qualsiasi wallet o exchange. Circa due secondi dopo il trasferimento è in un blocco. Il webhook scatta, il tuo server verifica la firma HMAC, e l'ordine passa a pagato. Nessun circuito carte, nessun chargeback, nessuna attesa degli orari bancari.

I dati della chain diventano obsoleti, quindi ecco quelli attuali con le date. Ai primi di luglio 2026:

I blocchi arrivano ogni 2-2,3 secondi in media, secondo i dati sul block time di PolygonScan, e la finalità della transazione si attesta intorno ai 5 secondi. Per i depositi questo significa che il divario tra "il cliente ha premuto invia" e "sicuro da accreditare" si misura in secondi a una cifra.

Il token gas è POL. La migrazione da MATIC è avvenuta il 4 settembre 2024, a un tasso 1:1, con i saldi sulla chain PoS convertiti automaticamente; Polygon ha riportato la migrazione completa al 99% circa un anno dopo. Ogni transazione su Polygon PoS da allora ha pagato il gas in POL.

La testnet è Amoy, ancorata alla Sepolia di Ethereum. Ha sostituito la vecchia testnet Mumbai, ritirata il 13 aprile 2024, insieme alla rete Goerli da cui dipendeva. I tutorial che dicono ancora Mumbai sono obsoleti; il flusso che descrivono di solito funziona su Amoy senza modifiche.

Ogni transazione Polygon paga il gas in POL, il token che ha sostituito MATIC a settembre 2024 a un tasso 1:1. L'indirizzo mittente ha bisogno di un piccolo saldo POL per questo; ricevere token non costa nulla al destinatario. Il prezzo del gas è impostato automaticamente dall'API, quindi le integrazioni raramente lo regolano a mano.

I saldi sulla chain PoS sono migrati da MATIC a POL automaticamente, quindi la documentazione più vecchia che dice ancora MATIC oggi significa POL. Il pattern abituale è un hot wallet finanziato per i payout, più trasferimenti di consolidamento dagli indirizzi di deposito che ricarichi con POL secondo necessità. Poiché un singolo trasferimento brucia solo una frazione minuscola di un POL, un saldo modesto copre molto traffico.

Ogni contratto ERC-20 standard su Polygon funziona. USDT, USDC e DAI sono supportati immediatamente, decimali inclusi. Se hai lanciato un tuo token, passa il suo contract address allo stesso endpoint e si comporterà come qualsiasi altro. NFT e token DeFi seguono la stessa regola. Poiché l'API è identica tra le chain, il codice scritto per Polygon gira anche contro Ethereum, BSC o Arbitrum una volta scambiato il segmento chain nell'URL.

Il throughput è abbastanza alto per il gaming e altri carichi ad alta frequenza, e i costi sono abbastanza bassi da rendere pratici casi d'uso esclusi da Ethereum L1. Grandi brand di consumo hanno lanciato programmi fedeltà e collezionabili su Polygon, il che ha portato utenti mainstream sulla rete, e progetti istituzionali continuano a sceglierla per la liquidazione. Per il tuo team il costo d'ingresso è basso: la chain è EVM-compatibile, quindi tutto ciò che sai su Ethereum si trasferisce invariato.

Tre richieste coprono l'intero ciclo di pagamento. Gli schemi esatti di richiesta sono nella documentazione API; per prove contro la testnet Polygon (Amoy), aggiungi l'header X-Network: testnet.

Importa un wallet esistente:

curl -X POST https://app.chaingateway.io/api/v2/polygon/addresses/import \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourAddress",
    "privatekey": "0xYourPrivateKey",
    "password": "YourWalletPassword"
  }'

La password protegge la key importata sulla piattaforma; gli invii successivi da quell'indirizzo passano la password invece della key grezza.

Invia USDT su Polygon (contratto 0xc2132D05D31c914a87C6611C10748AEb04B58e8F):

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractaddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "from": "0xYourSenderAddress",
    "to": "0xRecipientAddress",
    "amount": 5,
    "password": "YourWalletPassword"
  }'

Elenca le notifiche webhook passate, il modo più veloce per riconciliare i depositi con il tuo database:

curl https://app.chaingateway.io/api/v2/polygon/webhooks/notifications \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY"

Le stesse tre chiamate si traducono direttamente in PHP, Python o Node con qualsiasi client HTTP standard; non c'è alcuna libreria specifica per Polygon da installare.

Ecco il flusso completo di ricezione, come funziona in produzione anziché in una demo.

Mappatura degli indirizzi e attribuzione

Ogni cliente o ordine riceve il proprio indirizzo di deposito, memorizzato in un'unica tabella: il tuo ID interno, l'indirizzo, un timestamp. L'indirizzo in un payload webhook in entrata è la chiave di ricerca che lega un trasferimento a un ordine, e un indice univoco su quella colonna garantisce che nessun deposito possa mai corrispondere a due ordini. Se la tua piattaforma già gestisce le key, registrale una volta tramite POST /api/v2/polygon/addresses/import e collega webhook come descritto nella guida ai webhook.

Verificare e accreditare un deposito

Quando il cliente paga, il trasferimento è in un blocco entro circa due secondi e la notifica raggiunge il tuo endpoint poco dopo. Il tuo handler verifica prima la firma HMAC, cerca l'ordine per indirizzo, e poi controlla un'altra cosa prima di accreditare: se ha già visto questo hash di transazione. Memorizza ogni hash elaborato con un vincolo univoco e lascia che il database rifiuti i duplicati. Una consegna mancata dal tuo server non è persa: appare sotto GET /api/v2/polygon/webhooks/notifications/failed, e POST /api/v2/polygon/webhooks/notifications/{id}/retry la reinvia, così un timeout dal tuo lato non perde mai un deposito; l'elaborazione idempotente è ciò che impedisce a una notifica ripetuta di accreditarne uno due volte.

Quanto attendere prima di rilasciare i beni

Questa è una decisione di business, non tecnica. La finalità su Polygon arriva circa 5 secondi dopo l'inclusione, quindi anche una policy prudente costa poco: accredita un acquisto da 3 USDC alla prima notifica, trattieni un deposito a quattro cifre finché il tuo controllo di riconciliazione contro GET /api/v2/polygon/webhooks/notifications non lo conferma. Quell'endpoint funge anche da audit trail; un confronto notturno con il tuo libro contabile individua ciò che un'interruzione di due ore potrebbe aver nascosto.

Consolidare gli indirizzi di deposito

Gli indirizzi di deposito si riempiono nel tempo, quindi programma un consolidamento: un job che consolida i saldi nel tuo wallet di tesoreria con la stessa chiamata POST /api/v2/polygon/transactions/erc20, con from impostato sull'indirizzo di deposito. Ogni indirizzo consolidato ha bisogno di una traccia di POL per il gas, che ai prezzi di Polygon è abbastanza piccola da pre-finanziare in blocco.

I prelievi sono il flusso in cui gli errori costano denaro direttamente, e due abitudini eliminano la maggior parte del rischio.

Valida prima di mettere in coda. Un indirizzo di destinazione deve decodificarsi come un valore 0x di 20 byte, e quando contiene lettere maiuscole e minuscole miste, il checksum EIP-55 deve corrispondere. Rifiuta i fallimenti nel form, dove l'utente può correggere un errore di battitura; l'API valida di nuovo prima di trasmettere, ma prima si coglie l'errore, più economico è.

Scrivi prima, invia poi. Crea una riga di database per payout con una macchina a stati (queued, sent, confirmed), lascia che un worker faccia esattamente una chiamata POST /api/v2/polygon/transactions/erc20 per riga, e memorizza subito l'hash di transazione restituito. Dai all'utente quell'hash come link PolygonScan, e potrà tracciare il proprio prelievo invece di scrivere al supporto. Se la chiamata API va in timeout, non ripartire per riflesso: controlla l'elenco delle notifiche e i tuoi record per confermare che nulla sia uscito, poi ritenta deliberatamente. L'hot wallet ha bisogno di una riserva di POL per il gas; su Polygon un piccolo saldo copre migliaia di trasferimenti, quindi una ricarica mensile è sufficiente.

Amoy è la testnet di Polygon ancorata a Sepolia, attiva dai primi del 2024 come sostituto di Mumbai, e ogni endpoint di questa pagina gira contro di essa quando aggiungi un header:

X-Network: testnet

Nessun account separato, nessuna seconda key, nessun'altra modifica. Il POL di test proviene dai faucet pubblici Amoy, e gli indirizzi e la meccanica corrispondono esattamente a mainnet.

Dedica l'esecuzione di test ai percorsi di fallimento invece che a quello felice. Uccidi il tuo endpoint webhook, invia un deposito, riporta su l'endpoint, poi leggi l'elenco delle notifiche fallite e riproduci la consegna tramite l'endpoint di retry. Riproduci una notifica già elaborata e conferma che il tuo controllo di idempotenza la rifiuti. Invia due volte lo stesso payout e verifica che ne parta solo uno. Ogni prova richiede minuti su Amoy e previene un incidente reale in seguito; quando tutte e tre reggono, elimina l'header e il codice identico è in produzione.

Il tuo endpoint webhook alimenta il tuo libro contabile, quindi rafforzalo come qualsiasi altro input legato al denaro.

Prima la firma. Imposta un secret personale nelle impostazioni del tuo profilo, e ogni notifica porterà un header X-Signature: un HMAC-SHA256 in base64 del txid del payload, con quel secret come chiave. Ricalcolala e confrontala a tempo costante prima di toccare il resto del payload. Qualsiasi cosa fallisca riceve una risposta 4xx e nessuna elaborazione. Esempi di verifica in Python, Java, PHP e JavaScript sono nella guida ai webhook.

La whitelist IP di Chaingateway protegge l'altra direzione: nel pannello account puoi limitare l'accesso API a un elenco degli IP dei tuoi server, così una API key trapelata è inutile ovunque altro. Protegge la tua key, non il tuo receiver webhook — per il receiver, la firma è il controllo di autenticità. Contro le notifiche riprodotte, che portano firme valide per definizione, il tuo vincolo sull'hash di transazione è la difesa; un duplicato viene riconosciuto e scartato. Servi l'endpoint solo via HTTPS, e tieni i segreti fuori dall'URL, perché gli URL finiscono nei log di infrastrutture che non gestisci.

Gli errori tornano come codici di stato HTTP standard con corpi JSON, quindi i tuoi pattern abituali si applicano invariati.

Un 401 è un problema di autenticazione: il Bearer token manca, è stato revocato o digitato male. Altre risposte 4xx sono fallimenti di validazione, un checksum sbagliato o un campo sconosciuto, e il corpo indica il colpevole; ripetere la richiesta identica non può avere successo. Un 429 significa che è stato raggiunto il rate limit del piano; rallenta con ritardi crescenti, e guarda la pagina prezzi se lo incontri in operatività normale anziché a raffiche.

Per risposte 5xx, ritenta liberamente le letture. Ritenta gli invii solo dopo aver confermato, tramite l'elenco delle notifiche e le tue righe di payout, che il primo tentativo non è stato trasmesso. Tieni il corpo completo della risposta nei tuoi log accanto alla richiesta che l'ha causato; quell'abbinamento accorcia ogni sessione di debug e scambio con il supporto. Codici di stato e schemi di errore per endpoint sono nella documentazione API.

Il pattern centrale è l'accettazione di pagamenti: un indirizzo di deposito per ordine, un webhook per trasferimento in entrata, liquidazione in secondi. I commercianti lo usano per il checkout, e le piattaforme lo usano per i saldi utente, osservando i depositi ed elaborando prelievi su migliaia di indirizzi tramite gli stessi endpoint.

I bassi costi del gas aprono pattern che altrove sono impraticabili: micro-payout ai creator di contenuti, airdrop e piani di vesting eseguiti come semplici trasferimenti ERC-20, fatturazione ricorrente di abbonamenti in stablecoin, e pagamenti transfrontalieri dove la commissione è centesimi invece che una percentuale.