API RPC de Polygon: Configuración de endpoints, métodos y depuración

La API RPC de Polygon es la superficie JSON-RPC que tu aplicación utiliza para leer el estado de Polygon PoS y transmitir transacciones. Si estás configurando una billetera, un indexador backend o un frontend de dApp, necesitas tres cosas: la configuración correcta de la cadena, un patrón de solicitud funcional y una idea clara de qué fallos son de tu código y cuáles del endpoint. Esta página te da las tres, y luego te ayuda a decidir si un endpoint público compartido o un nodo dedicado de Polygon se ajusta a tu carga de trabajo.

Configuración de la cadena de un vistazo

Antes de enviar una sola solicitud, confirma los parámetros de la red. La mainnet de Polygon PoS y la testnet Polygon Amoy usan diferentes ID de cadena y diferentes símbolos de moneda nativa, y mezclarlos es uno de los errores de configuración más comunes.

Esos endpoints públicos son útiles para pruebas rápidas y lecturas de bajo volumen. Para tráfico de producción, se aplican límites de velocidad y capacidad compartida, por lo que la mayoría de los equipos pasan a un endpoint gestionado o dedicado. Puedes revisar la página completa de la red RPC de Polygon para transportes compatibles y opciones de acceso actuales.

Si estás agregando Polygon a una billetera o a un conmutador de red de frontend, la configuración generalmente se ve así:

const polygonMainnet = {
  chainId: '0x89', // 137
  chainName: 'Polygon Mainnet',
  nativeCurrency: { name: 'POL', symbol: 'POL', decimals: 18 },
  rpcUrls: ['https://polygon.api.onfinality.io/public'],
  blockExplorerUrls: ['https://polygonscan.com'],
};

Cómo decidir: endpoint público o nodo dedicado

La decisión generalmente se trata de la forma de la carga de trabajo, no de qué endpoint es "mejor" en abstracto. Usa la tabla a continuación para ubicar tu propio patrón de tráfico.

Una regla práctica: si tu aplicación puede tolerar respuestas 429 ocasionales y solo lee estado reciente, un endpoint compartido es suficiente. Si dependes de consultas de logs, estado histórico, llamadas de trace o rendimiento predecible, planifica una configuración gestionada o dedicada. OnFinality ofrece tanto acceso a la API RPC gestionada como nodos dedicados para equipos que necesitan capacidad aislada.

Enviando tu primera solicitud JSON-RPC de Polygon

Cada llamada RPC de Polygon sigue el mismo sobre JSON-RPC 2.0. Comienza con una verificación de estado simple para confirmar que el endpoint es accesible y devuelve la cadena esperada.

curl -s https://polygon.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

Una respuesta correcta devuelve el ID de cadena como una cadena hexadecimal:

{"jsonrpc":"2.0","id":1,"result":"0x89"}

Si obtienes 0x89, estás en la mainnet de Polygon. Si obtienes 0x13882, estás en la testnet Amoy (80002). Si obtienes un valor completamente diferente, tu endpoint está apuntando a otra red.

Leer un saldo sigue la misma forma:

curl -s https://polygon.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000001010","latest"]}'

En JavaScript, la misma llamada a través de ethers se ve así:

import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://polygon.api.onfinality.io/public');
const block = await provider.getBlockNumber();
const balance = await provider.getBalance('0x0000000000000000000000000000000000001010');
console.log({ block, balance: balance.toString() });

Métodos RPC de Polygon que realmente usarás

Polygon PoS es compatible con EVM, por lo que el conjunto de métodos coincide con Ethereum. Los métodos a continuación cubren la mayor parte del tráfico de producción.

Dos detalles específicos de Polygon vale la pena recordar. Primero, el token de gas nativo es POL, y la conocida dirección de tarifas 0x0000000000000000000000000000000000001010 se utiliza en la contabilidad de gas. Segundo, debido a que Polygon PoS ha tenido reorganizaciones y retrasos de sincronización de estado históricamente, los backends que indexan logs deben rastrear confirmaciones en lugar de asumir que un bloque es final en el momento en que aparece.

Suscripciones WebSocket para datos en vivo

Si necesitas actualizaciones push en lugar de sondeo, conéctate a través de WebSocket. El endpoint de Polygon de OnFinality admite tanto transporte HTTP como WebSocket.

import WebSocket from 'ws';

const ws = new WebSocket('wss://polygon.api.onfinality.io/public/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_subscribe',
    params: ['newHeads'],
  }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.method === 'eth_subscription') {
    console.log('New head:', msg.params.result.number);
  }
});

Las conexiones WebSocket son con estado. Si tu proceso se reinicia o el socket se cae, debes volver a suscribirte. Construye lógica de reconexión con retroceso exponencial y vuelve a obtener el último bloque al reconectar para no perder eventos durante el intervalo.

Ruta de depuración: fallos comunes de RPC de Polygon

Cuando una solicitud falla, el mensaje de error generalmente apunta a la causa. Usa esta tabla para pasar del síntoma a la solución.

Un bucle de diagnóstico rápido para un endpoint fallido:

# 1. ¿El endpoint está vivo y en la cadena correcta?
curl -s https://polygon.api.onfinality.io/public -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 2. ¿Está sincronizado con la cabeza?
curl -s https://polygon.api.onfinality.io/public -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

Si eth_chainId es correcto pero eth_blockNumber va por detrás de un explorador de bloques público, el nodo puede estar poniéndose al día. Si ambos tienen éxito pero tu aplicación sigue fallando, el problema probablemente esté en tu carga útil de solicitud, ABI o manejo de nonce en lugar del endpoint.

Lista de verificación de preparación para producción

Antes de dirigir tráfico real a cualquier endpoint de Polygon, confirma estos elementos:

• El ID de cadena y la moneda nativa coinciden con la red que pretendes usar (137 para mainnet, 80002 para Amoy).
• Tienes un endpoint o proveedor de respaldo en caso de que el principal no esté disponible.
• Las consultas de logs están divididas en rangos que el endpoint acepta.
• Los clientes WebSocket implementan reconexión y resuscripción.
• Monitoreas tasas de error, latencia y retraso de altura de bloque en lugar de solo verificar el tiempo de actividad.
• Las necesidades de archivo y trace se confirman con tu proveedor antes del lanzamiento, no después.

Una sonda de monitoreo simple te mantiene por delante de las interrupciones:

async function probe(url) {
  const start = Date.now();
  const res = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] }),
  });
  const json = await res.json();
  return { ok: res.ok, latencyMs: Date.now() - start, block: parseInt(json.result, 16) };
}

Ejecuta esto en un horario y alerta cuando la latencia aumente o la altura del bloque deje de avanzar.

Dónde encaja OnFinality

OnFinality proporciona acceso a la API RPC e infraestructura de nodos dedicados para Polygon y muchas otras redes. Para pruebas rápidas, los endpoints públicos anteriores son suficientes. Para aplicaciones de producción que necesitan rendimiento predecible, acceso a archivo o capacidad aislada, una configuración gestionada o dedicada elimina las limitaciones de los endpoints compartidos. Puedes comparar planes en la página de precios de RPC y explorar otras cadenas en la lista de redes RPC compatibles. Si aún estás sopesando proveedores, la guía de selección de proveedor de RPC recorre los criterios de evaluación que más importan.

Puntos clave

• La mainnet de Polygon usa el ID de cadena 137 y POL como moneda nativa; la testnet Amoy usa 80002.
• La API RPC de Polygon es compatible con EVM, por lo que se aplican los métodos JSON-RPC estándar de Ethereum.
• Los endpoints públicos son adecuados para pruebas y lecturas ligeras, pero las consultas de logs, datos de archivo y alto rendimiento generalmente necesitan un endpoint gestionado o dedicado.
• La mayoría de los fallos se remontan a límites de velocidad, límites de rango de logs, sincronización de nonce o datos de archivo faltantes, y cada uno tiene una solución específica.
• Monitorea la latencia y el retraso de altura de bloque, no solo el tiempo de actividad, y siempre mantén un endpoint de respaldo.

Preguntas frecuentes

¿Qué es la API RPC de Polygon?

Es la interfaz JSON-RPC que permite a tu aplicación leer el estado de Polygon PoS y enviar transacciones a través de un nodo. Sigue el estándar JSON-RPC 2.0 y admite el mismo conjunto de métodos que Ethereum porque Polygon PoS es compatible con EVM.

¿Cuál es el ID de cadena de Polygon?

La mainnet de Polygon usa el ID de cadena 137 (0x89). La testnet Polygon Amoy usa el ID de cadena 80002 (0x13882). Siempre confirma el ID de cadena con eth_chainId antes de enviar transacciones.

¿Polygon RPC admite WebSocket?

Sí. El endpoint de Polygon de OnFinality admite tanto transporte HTTP como WebSocket, lo que te permite suscribirte a newHeads, logs y otros eventos en lugar de sondear.

¿Por qué falla eth_getLogs en Polygon?

La mayoría de los fallos de consulta de logs provienen de solicitar un rango de bloques demasiado amplio. Los endpoints compartidos limitan el rango para proteger la capacidad. Divide tu consulta en ventanas más pequeñas o usa un proveedor que admita rangos más amplios.

¿Puedo usar un endpoint RPC público de Polygon en producción?

Puedes, pero los endpoints públicos compartidos aplican límites de velocidad y pueden no ofrecer datos de archivo o trace. Para tráfico de producción, un endpoint gestionado o dedicado te da un comportamiento más predecible.

¿Cómo obtengo POL de testnet para Amoy?

Usa un faucet de Polygon Amoy para solicitar POL de testnet para desarrollo. La red Amoy usa el mismo símbolo de token POL que la mainnet pero en una cadena separada, por lo que los fondos de testnet no tienen valor en mainnet.