Polygon Blockchain API : paiements en stablecoins à faible gas

La collision de noms mérite deux paragraphes de plus, car la moitié des résultats de recherche pour « polygon api » pointent vers le mauvais produit. Polygon.io est une entreprise américaine qui vend des flux de données de marché : cours boursiers, chaînes d'options, chandelles forex. Son API répond à des questions comme « à quel cours AAPL a-t-il été échangé hier ». Elle n'a aucune blockchain, aucun token et aucun lien avec le réseau couvert par cette page.

Polygon la blockchain, exploitée par Polygon Labs, est un réseau proof-of-stake compatible EVM qui règle des transactions de tokens. Sa surface API, qu'il s'agisse de JSON-RPC brut ou d'une couche de paiement comme Chaingateway, répond à des questions comme « l'USDC du client est-il arrivé » et exécute des instructions comme « payer 50 USDT ». Si vous avez besoin de tickers et de chandelles OHLC, fermez cet onglet et cherchez Polygon.io. Si vous avez besoin de déplacer des stablecoins avec des frais de gas mesurés en fractions de centime, continuez votre lecture.

La chose la plus courante construite sur les endpoints Polygon de Chaingateway est le traitement de paiements en stablecoins, et l'économie explique pourquoi. Chaque transfert ERC-20 nécessite du gas. Sur Ethereum mainnet, le gas pour un transfert USDT peut coûter plus qu'un petit paiement lui-même ; sur Polygon, le même transfert coûte au plus quelques centimes. Facturer quelqu'un 2 USDC pour un produit numérique est viable ici. Sur L1, ça ne l'est pas.

Les chiffres confirment cela. Mi-2026, les traqueurs de frais situent un transfert USDT typique sur Polygon PoS entre un dixième de centime et deux centimes, et il dépasse rarement quelques centimes même quand le réseau est chargé. Le même transfert sur Ethereum mainnet a varié de bien moins d'un dollar les semaines calmes à plusieurs dollars pendant les pics de congestion. L'écart bouge avec les marchés du gas, mais il s'est maintenu à deux ou trois ordres de grandeur pendant des années, et pour un modèle économique construit sur de petits paiements, cet écart est tout le business case.

Un checkout typique ressemble à ceci : votre backend assigne au client une adresse de dépôt et affiche un QR code, et le client envoie de l'USDC ou de l'USDT depuis n'importe quel wallet ou plateforme d'échange. Environ deux secondes plus tard, le transfert est dans un bloc. Le webhook se déclenche, votre serveur vérifie la signature HMAC, et la commande bascule sur payée. Pas de réseaux de carte, pas de rétrofacturations, pas d'attente d'horaires bancaires.

Les faits sur les chaînes dérivent, voici donc les chiffres actuels avec des dates. Au début juillet 2026 :

Les blocs arrivent tous les 2 à 2,3 secondes en moyenne, selon les données de temps de bloc de PolygonScan, et la finalité de transaction se situe autour de 5 secondes. Pour les dépôts, cela signifie que l'écart entre « le client a appuyé sur envoyer » et « sûr à créditer » se mesure en secondes à un seul chiffre.

Le token de gas est le POL. La migration depuis MATIC a eu lieu le 4 septembre 2024, à un taux 1:1, avec les soldes sur la chaîne PoS convertis automatiquement ; Polygon a rapporté la migration achevée à 99 % environ un an plus tard. Chaque transaction sur Polygon PoS paie du gas en POL depuis lors.

Le testnet est Amoy, ancré au Sepolia d'Ethereum. Il a remplacé l'ancien testnet Mumbai, retiré le 13 avril 2024, en même temps que le réseau Goerli dont il dépendait. Les tutoriels qui mentionnent encore Mumbai sont obsolètes ; le flux qu'ils décrivent fonctionne généralement sans changement sur Amoy.

Chaque transaction Polygon paie du gas en POL, le token qui a remplacé MATIC en septembre 2024 à un taux 1:1. L'adresse expéditrice a besoin d'un petit solde POL pour cela ; recevoir des tokens ne coûte rien au destinataire. Le prix du gas est fixé automatiquement par l'API, donc les intégrations l'ajustent rarement manuellement.

Les soldes sur la chaîne PoS ont migré de MATIC vers POL automatiquement, donc une documentation plus ancienne qui dit encore MATIC désigne du POL aujourd'hui. Le schéma habituel est un hot wallet alimenté pour les paiements sortants, plus des transferts de consolidation depuis les adresses de dépôt que vous rechargez en POL selon les besoins. Comme un seul transfert ne brûle qu'une infime fraction d'un POL, un flottant modeste couvre beaucoup de trafic.

Tout contrat ERC-20 standard sur Polygon fonctionne. USDT, USDC et DAI sont supportés d'emblée, décimales incluses. Si vous avez lancé votre propre token, passez son adresse de contrat au même endpoint et il se comporte comme n'importe quel autre. Les NFT et tokens DeFi suivent la même règle. Comme l'API est identique sur toutes les chaînes, du code écrit pour Polygon tourne aussi contre Ethereum, BSC ou Arbitrum une fois que vous échangez le segment de chaîne dans l'URL.

Le débit est assez élevé pour le gaming et d'autres charges de travail à haute fréquence, et les coûts sont assez bas pour que des cas d'usage exclus d'Ethereum L1 deviennent praticables. De grandes marques grand public ont lancé des programmes de fidélité et des objets de collection sur Polygon, ce qui a attiré des utilisateurs grand public sur le réseau, et des projets institutionnels continuent de le choisir pour le règlement. Pour votre équipe, le coût d'entrée est faible : la chaîne est compatible EVM, donc tout ce que vous savez sur Ethereum se transpose sans changement.

Trois requêtes couvrent toute la boucle de paiement. Les schémas de requête exacts sont dans la référence API ; pour des essais à blanc contre le testnet Polygon (Amoy), ajoutez l'en-tête X-Network: testnet.

Importer un wallet existant :

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"
  }'

Le mot de passe protège la clé importée sur la plateforme ; les envois ultérieurs depuis cette adresse passent le mot de passe plutôt que la clé brute.

Envoyer de l'USDT sur Polygon (contrat 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"
  }'

Lister les notifications de webhook passées, le moyen le plus rapide de réconcilier les dépôts avec votre base de données :

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

Les trois mêmes appels se traduisent directement en PHP, Python ou Node avec n'importe quel client HTTP standard ; il n'y a aucune bibliothèque spécifique à Polygon à installer.

Voici le flux de réception complet, tel qu'il tourne en production plutôt que dans une démo.

Correspondance d'adresse et attribution

Chaque client ou commande obtient sa propre adresse de dépôt, stockée dans une table : votre identifiant interne, l'adresse, un horodatage. L'adresse dans un payload de webhook entrant est la clé de recherche qui lie un transfert à une commande, et un index unique sur cette colonne garantit qu'aucun dépôt ne peut jamais correspondre à deux commandes. Si votre plateforme gère déjà des clés, enregistrez-les une fois via POST /api/v2/polygon/addresses/import et attachez des webhooks comme décrit dans le guide des webhooks.

Vérifier et créditer un dépôt

Quand le client paie, le transfert est dans un bloc en environ deux secondes et la notification atteint votre endpoint peu après. Votre handler vérifie d'abord la signature HMAC, recherche la commande par adresse, puis vérifie une chose de plus avant de créditer : s'il a déjà vu ce hash de transaction. Stockez chaque hash traité avec une contrainte unique et laissez la base de données refuser les doublons. Une livraison que votre serveur a manquée n'est pas perdue : elle apparaît sous GET /api/v2/polygon/webhooks/notifications/failed, et POST /api/v2/polygon/webhooks/notifications/{id}/retry la renvoie, si bien qu'un timeout de votre côté ne perd jamais un dépôt ; le traitement idempotent est ce qui empêche une notification rejouée de créditer deux fois.

Combien de temps attendre avant de libérer des biens

C'est une décision métier, pas technique. La finalité sur Polygon arrive environ 5 secondes après l'inclusion, donc même une politique prudente coûte peu : créditez un achat de 3 USDC à la première notification, retenez un dépôt à quatre chiffres jusqu'à ce que votre vérification de réconciliation contre GET /api/v2/polygon/webhooks/notifications le confirme. Cet endpoint sert aussi de piste d'audit ; un diff nocturne contre votre propre registre capture tout ce qu'une interruption de deux heures aurait pu masquer.

Balayer les adresses de dépôt

Les adresses de dépôt se remplissent avec le temps, planifiez donc un balayage : une tâche qui consolide les soldes vers votre wallet de trésorerie avec le même appel POST /api/v2/polygon/transactions/erc20, from réglé sur l'adresse de dépôt. Chaque adresse balayée a besoin d'une trace de POL pour le gas, ce qui aux prix de Polygon est assez faible pour être préfinancé en masse.

Les retraits sont le flux où les erreurs coûtent directement de l'argent, et deux habitudes suppriment la majeure partie du risque.

Validez avant de mettre en file. Une adresse de destination doit se décoder comme une valeur 0x de 20 octets, et quand elle contient des lettres mixtes, la checksum EIP-55 doit correspondre. Rejetez les échecs au formulaire, où l'utilisateur peut corriger une faute de frappe ; l'API valide à nouveau avant la diffusion, mais plus tôt vous l'attrapez, moins ça coûte.

Écrivez d'abord, envoyez ensuite. Créez une ligne de base de données par paiement avec une machine à états (queued, sent, confirmed), laissez un worker faire exactement un appel POST /api/v2/polygon/transactions/erc20 par ligne, et stockez le hash de transaction retourné immédiatement. Donnez à l'utilisateur ce hash comme lien PolygonScan, et il peut suivre son propre retrait plutôt que d'écrire au support. Si l'appel API expire, ne tirez pas à nouveau par réflexe : vérifiez la liste de notifications et vos propres enregistrements pour confirmer que rien n'est sorti, puis réessayez délibérément. Le hot wallet a besoin d'un flottant de POL pour le gas ; sur Polygon un petit solde couvre des milliers de transferts, donc une recharge mensuelle suffit.

Amoy est le testnet de Polygon ancré au Sepolia, actif depuis début 2024 en remplacement de Mumbai, et chaque endpoint de cette page tourne contre lui quand vous ajoutez un en-tête :

X-Network: testnet

Aucun compte séparé, aucune seconde clé, aucun autre changement. Le POL de test provient des faucets publics Amoy, et les adresses et la mécanique correspondent exactement au mainnet.

Consacrez l'essai aux chemins d'échec plutôt qu'au chemin heureux. Coupez votre endpoint webhook, envoyez un dépôt, remettez l'endpoint en ligne, puis lisez la liste des notifications échouées et rejouez la livraison via l'endpoint de retry. Rejouez une notification déjà traitée et confirmez que votre vérification d'idempotence la rejette. Soumettez le même paiement sortant deux fois et vérifiez qu'un seul part. Chaque répétition prend des minutes sur Amoy et évite un vrai incident plus tard ; quand les trois tiennent, retirez l'en-tête et le code identique est en production.

Votre endpoint webhook alimente votre registre, durcissez-le donc comme toute autre entrée proche de l'argent.

Signature d'abord. Définissez un secret personnel dans vos paramètres de profil, et chaque notification porte un en-tête X-Signature : un HMAC-SHA256 encodé en base64 du txid du payload, avec ce secret comme clé. Recalculez-le et comparez à temps constant avant de toucher le reste du payload. Tout ce qui échoue reçoit une réponse 4xx et aucun traitement. Des exemples de vérification en Python, Java, PHP et JavaScript sont dans le guide des webhooks.

La liste blanche IP de Chaingateway garde l'autre direction : dans le panneau de compte, vous pouvez limiter l'accès API à une liste des IP de vos propres serveurs, si bien qu'une clé API fuitée est inutile ailleurs. Elle protège votre clé, pas votre récepteur de webhook — pour le récepteur, la signature est la vérification d'authenticité. Contre les notifications rejouées, qui portent par définition des signatures valides, votre contrainte de hash de transaction est la défense ; un doublon est acquitté et abandonné. Servez l'endpoint uniquement en HTTPS, et gardez les secrets hors de l'URL, car les URL fuitent dans des logs sur une infrastructure que vous n'exploitez pas.

Les erreurs reviennent comme des codes de statut HTTP standards avec des corps JSON, donc vos modèles habituels s'appliquent sans changement.

Un 401 est un problème d'authentification : le jeton Bearer est manquant, révoqué ou mal saisi. D'autres réponses 4xx sont des échecs de validation, une mauvaise checksum ou un champ inconnu, et le corps nomme le coupable ; réessayer la requête identique ne peut pas réussir. Un 429 signifie que la limite de débit du forfait est atteinte ; ralentissez avec des délais croissants, et consultez la page de tarification si vous l'atteignez en exploitation normale plutôt qu'en rafales.

Pour les réponses 5xx, réessayez librement les lectures. Réessayez les envois seulement après avoir confirmé, via la liste de notifications et vos propres lignes de paiement, que la première tentative n'a pas été diffusée. Gardez le corps de réponse complet dans vos logs à côté de la requête qui l'a causé ; cette association raccourcit chaque session de débogage et échange avec le support. Les codes de statut et schémas d'erreur par endpoint sont dans la référence API.

Le schéma central est l'acceptation de paiements : une adresse de dépôt par commande, un webhook par transfert entrant, un règlement en quelques secondes. Les marchands l'utilisent pour le checkout, et les plateformes l'utilisent pour les soldes utilisateur, en surveillant les dépôts et en traitant les retraits sur des milliers d'adresses via les mêmes endpoints.

Les faibles coûts de gas ouvrent des schémas mort-nés ailleurs : micro-paiements aux créateurs de contenu, airdrops et calendriers de vesting exécutés comme de simples transferts ERC-20, facturation d'abonnement récurrente en stablecoins, et paiements transfrontaliers où les frais se mesurent en centimes plutôt qu'en pourcentage.