Polygon Blockchain API: Pagos en Stablecoins con Gas Bajo

La coincidencia de nombres merece dos párrafos más, porque la mitad de los resultados de búsqueda de "polygon api" apuntan al producto equivocado. Polygon.io es una empresa estadounidense que vende feeds de datos de mercado: cotizaciones bursátiles, cadenas de opciones, velas de forex. Su API responde preguntas como "¿a cuánto cotizó AAPL ayer". No tiene blockchain, ni tokens, ni conexión con la red que cubre esta página.

Polygon la blockchain, operada por Polygon Labs, es una red proof-of-stake compatible con EVM que liquida transacciones de tokens. Su superficie de API, sea JSON-RPC en bruto o una capa de pagos como Chaingateway, responde preguntas como "¿llegó el USDC del cliente" y ejecuta instrucciones como "paga 50 USDT". Si necesitas tickers y velas OHLC, cierra esta pestaña y busca Polygon.io. Si necesitas mover stablecoins con comisiones de gas medidas en fracciones de centavo, sigue leyendo.

Lo más común que se construye sobre los endpoints de Polygon de Chaingateway es el procesamiento de pagos en stablecoins, y la economía explica por qué. Cada transferencia ERC-20 necesita gas. En Ethereum mainnet, el gas de una transferencia de USDT puede costar más que el propio pago pequeño; en Polygon, la misma transferencia cuesta como mucho centavos. Cobrar a alguien 2 USDC por un producto digital es viable aquí. En L1 no lo es.

Las cifras lo respaldan. A mediados de 2026, los trackers de comisiones sitúan una transferencia típica de USDT en Polygon PoS entre una décima de centavo y dos centavos, y rara vez supera unos pocos centavos incluso con la red ocupada. La misma transferencia en Ethereum mainnet ha oscilado entre bastante menos de un dólar en semanas tranquilas y varios dólares durante picos de congestión. La brecha se mueve con los mercados de gas, pero se ha mantenido en dos o tres órdenes de magnitud durante años, y para un modelo de negocio basado en pagos pequeños esa brecha es todo el caso de negocio.

Un checkout típico se ve así: tu backend asigna al cliente una dirección de depósito y muestra un código QR, y el cliente envía USDC o USDT desde cualquier wallet o exchange. Unos dos segundos después la transferencia está en un bloque. El webhook se dispara, tu servidor verifica la firma HMAC, y el pedido pasa a pagado. Sin redes de tarjetas, sin contracargos, sin esperar al horario bancario.

Los datos de la chain se desactualizan, así que aquí están los actuales con fechas. A principios de julio de 2026:

Los bloques llegan cada 2 a 2,3 segundos de media, según los datos de tiempo de bloque de PolygonScan, y la finalidad de la transacción se sitúa en torno a los 5 segundos. Para los depósitos eso significa que la brecha entre "el cliente pulsó enviar" y "seguro para acreditar" se mide en segundos de un solo dígito.

El token de gas es POL. La migración desde MATIC ocurrió el 4 de septiembre de 2024, a una tasa de 1:1, con los saldos en la chain PoS convertidos automáticamente; Polygon informó que la migración estaba completa al 99% aproximadamente un año después. Cada transacción en Polygon PoS desde entonces ha pagado el gas en POL.

La testnet es Amoy, anclada a Sepolia de Ethereum. Reemplazó a la antigua testnet Mumbai, que se retiró el 13 de abril de 2024, junto con la red Goerli de la que dependía. Los tutoriales que todavía dicen Mumbai están desactualizados; el flujo que describen suele funcionar en Amoy sin cambios.

Cada transacción de Polygon paga el gas en POL, el token que reemplazó a MATIC en septiembre de 2024 a una tasa de 1:1. La dirección remitente necesita un pequeño saldo de POL para eso; recibir tokens no cuesta nada al destinatario. El precio del gas lo fija automáticamente la API, así que las integraciones rara vez lo ajustan a mano.

Los saldos en la chain PoS migraron de MATIC a POL automáticamente, así que la documentación antigua que todavía dice MATIC hoy significa POL. El patrón habitual es una hot wallet financiada para pagos, más transferencias de consolidación desde direcciones de depósito que recargas con POL según haga falta. Como una sola transferencia quema solo una fracción minúscula de un POL, un saldo modesto cubre mucho tráfico.

Cada contrato ERC-20 estándar en Polygon funciona. USDT, USDC y DAI están soportados de fábrica, decimales incluidos. Si lanzaste tu propio token, pasa su contract address al mismo endpoint y se comportará como cualquier otro. Los NFTs y los tokens DeFi siguen la misma regla. Como la API es idéntica entre chains, el código escrito para Polygon también se ejecuta contra Ethereum, BSC o Arbitrum en cuanto cambies el segmento de chain en la URL.

El rendimiento es lo bastante alto para gaming y otras cargas de alta frecuencia, y los costes son lo bastante bajos como para que casos de uso descartados en Ethereum L1 se vuelvan prácticos. Grandes marcas de consumo han lanzado programas de fidelidad y coleccionables en Polygon, lo cual ha atraído usuarios convencionales a la red, y proyectos institucionales siguen eligiéndola para liquidación. Para tu equipo el coste de entrada es bajo: la chain es EVM-compatible, así que todo lo que sabes sobre Ethereum se traslada sin cambios.

Tres solicitudes cubren todo el ciclo de pago. Los esquemas exactos de solicitud están en la referencia de la API; para ensayos contra la testnet de Polygon (Amoy), añade la cabecera X-Network: testnet.

Importa una wallet existente:

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 contraseña protege la key importada en la plataforma; los envíos posteriores desde esa dirección pasan la contraseña en lugar de la key en bruto.

Envía USDT en Polygon (contrato 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"
  }'

Lista las notificaciones de webhook pasadas, la forma más rápida de conciliar depósitos contra tu base de datos:

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

Las mismas tres llamadas se trasladan directamente a PHP, Python o Node con cualquier cliente HTTP estándar; no hay ninguna librería específica de Polygon que instalar.

Aquí está el flujo de recepción completo, tal como funciona en producción y no en una demo.

Mapeo de direcciones y atribución

Cada cliente o pedido recibe su propia dirección de depósito, guardada en una tabla: tu ID interno, la dirección, una marca de tiempo. La dirección en un payload de webhook entrante es la clave de búsqueda que liga una transferencia a un pedido, y un índice único en esa columna garantiza que ningún depósito pueda coincidir jamás con dos pedidos. Si tu plataforma ya gestiona keys, regístralas una vez mediante POST /api/v2/polygon/addresses/import y añade webhooks según se describe en la guía de webhooks.

Verificar y acreditar un depósito

Cuando el cliente paga, la transferencia está en un bloque en unos dos segundos y la notificación llega a tu endpoint momentos después. Tu manejador verifica primero la firma HMAC, busca el pedido por dirección, y luego comprueba una cosa más antes de acreditar: si ya ha visto este hash de transacción antes. Guarda cada hash procesado con una restricción única y deja que la base de datos rechace duplicados. Una entrega que tu servidor no recibió no está perdida: aparece bajo GET /api/v2/polygon/webhooks/notifications/failed, y POST /api/v2/polygon/webhooks/notifications/{id}/retry la reenvía, así que un timeout de tu lado nunca pierde un depósito; el procesamiento idempotente es lo que evita que una notificación reproducida acredite uno dos veces.

Cuánto esperar antes de liberar bienes

Eso es una decisión de negocio, no técnica. La finalidad en Polygon llega unos 5 segundos después de la inclusión, así que incluso una política cautelosa cuesta poco: acredita una compra de 3 USDC tras la primera notificación, retén un depósito de cuatro cifras hasta que tu comprobación de conciliación contra GET /api/v2/polygon/webhooks/notifications lo confirme. Ese endpoint hace también de rastro de auditoría; una comparación nocturna contra tu propia contabilidad detecta cualquier cosa que una interrupción de dos horas pudiera haber ocultado.

Consolidar direcciones de depósito

Las direcciones de depósito se llenan con el tiempo, así que programa una consolidación: un trabajo que consolida saldos en tu wallet de tesorería con la misma llamada POST /api/v2/polygon/transactions/erc20, con from fijado a la dirección de depósito. Cada dirección consolidada necesita una traza de POL para el gas, que a los precios de Polygon es lo bastante pequeña como para pre-financiar en bloque.

Los retiros son el flujo donde los errores cuestan dinero directamente, y dos hábitos eliminan la mayor parte del riesgo.

Valida antes de poner en cola. Una dirección de destino debe decodificar como un valor 0x de 20 bytes, y cuando contiene letras en mayúscula y minúscula mezcladas, el checksum EIP-55 debe coincidir. Rechaza los fallos en el formulario, donde el usuario puede corregir un error tipográfico; la API vuelve a validar antes de transmitir, pero cuanto antes se detecte, más barato es.

Escribe primero, envía después. Crea una fila de base de datos por pago con una máquina de estados (queued, sent, confirmed), deja que un worker haga exactamente una llamada POST /api/v2/polygon/transactions/erc20 por fila, y guarda el hash de transacción devuelto de inmediato. Da al usuario ese hash como un enlace de PolygonScan, y podrá seguir su propio retiro en lugar de escribir a soporte. Si la llamada a la API hace timeout, no dispares de nuevo por reflejo: comprueba la lista de notificaciones y tus propios registros para confirmar que nada salió, y luego reintenta deliberadamente. La hot wallet necesita un colchón de POL para el gas; en Polygon un saldo pequeño cubre miles de transferencias, así que una recarga mensual basta.

Amoy es la testnet de Polygon anclada a Sepolia, activa desde principios de 2024 como reemplazo de Mumbai, y cada endpoint de esta página se ejecuta contra ella cuando añades una cabecera:

X-Network: testnet

Sin cuenta separada, sin segunda key, sin ningún otro cambio. El POL de prueba viene de los faucets públicos de Amoy, y las direcciones y la mecánica coinciden exactamente con mainnet.

Dedica la ejecución de prueba a las rutas de fallo en lugar de al camino feliz. Mata tu endpoint de webhook, envía un depósito, reactiva el endpoint, y luego lee la lista de notificaciones fallidas y reproduce la entrega a través del endpoint de reintento. Reproduce una notificación que ya procesaste y confirma que tu comprobación de idempotencia la rechaza. Envía el mismo pago dos veces y verifica que solo sale uno. Cada ensayo toma minutos en Amoy y evita un incidente real más adelante; cuando los tres se sostengan, elimina la cabecera y el código idéntico estará en producción.

Tu endpoint de webhook alimenta tu contabilidad, así que refuérzalo como cualquier otra entrada relacionada con el dinero.

Firma primero. Fija un secreto personal en la configuración de tu perfil, y cada notificación llevará una cabecera X-Signature: un HMAC-SHA256 en base64 del txid del payload, con ese secreto como key. Recalcúlala y compárala en tiempo constante antes de tocar el resto del payload. Cualquier cosa que falle recibe una respuesta 4xx y ningún procesamiento. Ejemplos de verificación en Python, Java, PHP y JavaScript están en la guía de webhooks.

La lista blanca de IPs de Chaingateway protege la otra dirección: en el panel de la cuenta puedes limitar el acceso a la API a una lista de IPs de tus propios servidores, así que una API key filtrada es inútil desde cualquier otro sitio. Protege tu key, no tu receptor de webhooks — para el receptor, la firma es la comprobación de autenticidad. Contra notificaciones reproducidas, que llevan firmas válidas por definición, tu restricción por hash de transacción es la defensa; un duplicado se reconoce y se descarta. Sirve el endpoint solo por HTTPS, y mantén los secretos fuera de la URL, porque las URLs se filtran a registros en infraestructura que no operas.

Los errores vuelven como códigos de estado HTTP estándar con cuerpos JSON, así que tus patrones habituales aplican sin cambios.

Un 401 es un problema de autenticación: el Bearer token falta, fue revocado o está mal escrito. Otras respuestas 4xx son fallos de validación, un checksum malo o un campo desconocido, y el cuerpo nombra al culpable; reintentar la solicitud idéntica no puede tener éxito. Un 429 significa que se alcanzó el límite de tasa del plan; retrocede con retrasos crecientes, y mira la página de precios si lo alcanzas en operación normal en lugar de en ráfagas.

Para respuestas 5xx, reintenta lecturas libremente. Reintenta envíos solo después de haber confirmado, vía la lista de notificaciones y tus propias filas de pago, que el primer intento no se transmitió. Guarda el cuerpo completo de la respuesta en tus logs junto a la solicitud que lo causó; ese emparejamiento acorta cada sesión de depuración e intercambio de soporte. Los códigos de estado y esquemas de error por endpoint están en la referencia de la API.

El patrón central es la aceptación de pagos: una dirección de depósito por pedido, un webhook por transferencia entrante, liquidación en segundos. Los comercios lo usan para el checkout, y las plataformas lo usan para saldos de usuario, observando depósitos y procesando retiros a través de miles de direcciones mediante los mismos endpoints.

Los bajos costes de gas abren patrones que en otro sitio nacen muertos: micro-pagos a creadores de contenido, airdrops y calendarios de vesting ejecutados como simples transferencias ERC-20, facturación de suscripciones recurrentes en stablecoins, y pagos transfronterizos donde la comisión es de centavos en lugar de un porcentaje.