¿Cómo agrego la red Polygon a MetaMask?

MetaMask no viene con Polygon habilitado por defecto, así que la primera vez que quieras usar una dApp de Polygon tendrás que agregar la red manualmente o dejar que la dApp te lo solicite. La configuración es breve, pero la URL RPC que elijas decide si la billetera sigue siendo utilizable después de la primera transacción.

Esta página te proporciona los valores exactos de Polygon mainnet y Amoy testnet, una configuración de billetera para copiar y pegar, y una forma práctica de decidir a qué endpoint apuntar MetaMask.

¿Qué red Polygon deberías agregar primero?

La mayoría de las personas que buscan esto intentan hacer una de tres cosas, y la red correcta depende de cuál sea tu caso.

Si interactúas con fondos reales o una dApp en producción, agrega Polygon Mainnet. Si eres desarrollador y despliegas contratos, agrega Amoy como segunda red y mantén Mainnet para verificaciones de solo lectura. Mumbai era la testnet antigua y ya no es la que se debe usar para nuevos trabajos.

Una nota rápida sobre el token de gas: Polygon migró su token nativo de MATIC a POL. MetaMask aún puede mostrar la etiqueta antigua MATIC en algunas versiones, pero el símbolo que ingreses al agregar la red debe ser POL para configuraciones actuales.

Configuración de la cadena Polygon para MetaMask

Estos son los valores que ingresas en el formulario Agregar red. Mantenlos consistentes entre tu billetera, tus scripts y tu backend.

OnFinality expone ambas redes como endpoints de API RPC, y puedes revisar los detalles completos de la red en la página RPC de Polygon. Si prefieres ejecutar tu propio endpoint en lugar de uno compartido, eso se cubre en nodos dedicados.

Agregar Polygon a MetaMask paso a paso

1. Abre MetaMask y haz clic en el selector de redes en la parte superior de la billetera.
2. Elige Agregar red, luego Agregar una red manualmente.
3. Completa los campos de la tabla anterior. Verifica el ID de cadena: 137 para mainnet, 80002 para Amoy.
4. Guarda, luego cambia a la nueva red.
5. Confirma que el cambio funcionó verificando que el saldo de tu dirección se cargue y que el nombre de la red muestre Polygon.

Si una dApp ofrece un botón de Agregar Polygon con un clic, enviará los mismos valores a MetaMask a través de wallet_addEthereumChain. De todos modos terminas con la misma configuración, así que vale la pena conocer los valores en caso de que el mensaje falle.

Agregar la red desde código

Si estás construyendo una dApp y quieres agregar o cambiar redes programáticamente, usa los métodos RPC de la billetera directamente. Esta es la misma carga útil que MetaMask espera cuando un usuario hace clic en un botón de agregar red.

// Add Polygon Mainnet to an injected wallet
await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [
    {
      chainId: "0x89", // 137 in hex
      chainName: "Polygon",
      nativeCurrency: { name: "POL", symbol: "POL", decimals: 18 },
      rpcUrls: ["https://polygon.api.onfinality.io/public"],
      blockExplorerUrls: ["https://polygonscan.com"],
    },
  ],
});

// Switch to it if the user is on another chain
await window.ethereum.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0x89" }],
});

Ten en cuenta que chainId en estas llamadas está en hexadecimal, mientras que el formulario de MetaMask usa decimal. Mezclar los dos es una de las razones más comunes por las que un mensaje de agregar red falla silenciosamente.

Elegir una URL RPC que sobreviva al uso real

Esta es la parte que la mayoría de las guías de configuración omiten, y es donde la gente se queda atascada una semana después. La URL RPC es el endpoint que tu billetera usa para cada verificación de saldo, estimación de gas y transmisión de transacciones. Un endpoint público que funciona para una sola transacción de prueba puede comenzar a devolver errores una vez que lo consultas constantemente o envías ráfagas de solicitudes.

Cuando evalúes un endpoint para MetaMask o una dApp, fíjate en estas señales en lugar de una sola prueba de velocidad:

OnFinality proporciona acceso a API RPC e infraestructura de nodos dedicados en una variedad de redes, para que puedas comenzar en un endpoint compartido y pasar a un nodo dedicado cuando tu volumen de solicitudes o necesidades de latencia crezcan. Puedes comparar opciones en la página de precios de RPC y ver la lista completa en redes RPC compatibles.

Para MetaMask específicamente, un endpoint compartido suele ser suficiente para uso personal. Para una dApp con muchos usuarios, un nodo dedicado elimina el problema del vecino ruidoso donde el tráfico de otro proyecto afecta tus tiempos de respuesta.

Verifica la conexión antes de confiar en ella

Después de agregar la red, confirma que el endpoint realmente responde. Puedes probarlo fuera de la billetera con una simple llamada JSON-RPC.

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

La respuesta debe devolver 0x89, que es 137 en hexadecimal. Si obtienes un valor diferente, estás apuntando a la red incorrecta. También puedes verificar el último bloque para confirmar que el endpoint está sincronizado:

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

Si eth_chainId funciona pero eth_blockNumber va por detrás de un explorador de bloques, el nodo puede estar poniéndose al día o el endpoint puede estar bajo carga. Esa es una señal para cambiar de endpoint en lugar de reintentar en la billetera.

Problemas comunes después de agregar Polygon

La mayoría de los problemas que encuentra la gente no son errores de MetaMask. Se dividen en unas pocas categorías repetibles.

Transacciones atascadas como pendientes. Esto suele ser un problema de precio de gas o nonce, no un problema de red. Verifica la transacción en Polygonscan y, si es necesario, acelerala o cancelala en MetaMask.

El saldo muestra cero después de cambiar. Confirma que estás en la cadena correcta (137 vs 80002) y que el token está agregado a la billetera. POL es el token nativo; otros tokens deben importarse por dirección de contrato.

Errores RPC o tiempos de espera. Los endpoints públicos limitan la tasa. Si ves repetidos errores -32005 o de tiempo de espera, cambia a una URL RPC diferente o pasa a un endpoint dedicado.

ID de cadena incorrecto. Si una dApp informa la red incorrecta, vuelve a verificar que ingresaste 137 y no un ID de testnet. Las discrepancias de ID de cadena causan fallos de firma y transacción que parecen no relacionados.

Faltan tokens de testnet. Amoy requiere POL de prueba de un faucet. El POL de mainnet no se puede usar en Amoy, y el POL de testnet no tiene valor.

Cuándo dejar un endpoint público

Una URL RPC pública es un punto de partida razonable. Deja de ser razonable cuando cualquiera de las siguientes condiciones se cumple:

• Tu dApp tiene usuarios reales y no puedes tolerar errores RPC intermitentes.
• Necesitas datos de archivo para saldos o registros históricos.
• Dependes de suscripciones WebSocket para actualizaciones en tiempo real.
• Estás enviando suficientes solicitudes como para que los límites de tasa compartidos se interpongan.
• Necesitas un canal de soporte cuando algo se rompe.

En ese punto, la decisión es entre un endpoint compartido gestionado y un nodo dedicado. Los endpoints compartidos son más baratos y simples; los nodos dedicados te dan capacidad aislada y un comportamiento más predecible bajo carga. Si estás evaluando proveedores en general, la guía de selección de proveedor RPC repasa los criterios con más profundidad.

Puntos clave

• Polygon Mainnet usa el ID de cadena 137 y POL como token de gas; la testnet Amoy usa 80002.
• Puedes agregar la red manualmente en MetaMask o mediante wallet_addEthereumChain desde una dApp.
• La URL RPC es la configuración que más importa con el tiempo, porque los endpoints públicos limitan la tasa bajo carga.
• Verifica tu endpoint con eth_chainId y eth_blockNumber antes de confiar en él en producción.
• Pasa a un nodo dedicado cuando los límites compartidos, las necesidades de archivo o los requisitos de WebSocket comiencen a bloquearte.

Preguntas frecuentes

¿Polygon es lo mismo que MATIC? Polygon es la red; MATIC era el símbolo del token nativo anterior. La red ahora usa POL, aunque algunas billeteras todavía muestran la etiqueta antigua.

¿Qué ID de cadena usa Polygon? Polygon Mainnet es 137. Polygon Amoy testnet es 80002. En las llamadas RPC de la billetera, 137 es 0x89.

¿Necesito una URL RPC especial para MetaMask? No. Cualquier endpoint RPC de Polygon que funcione servirá. Un endpoint gestionado es más confiable que uno público una vez que usas la billetera con regularidad o ejecutas una dApp.

¿Puedo usar la misma URL RPC para mainnet y testnet? No. Mainnet y Amoy son redes separadas con endpoints separados e ID de cadena separados. Mantén ambas configuradas si desarrollas en Polygon.

¿Por qué MetaMask dice que la red no está disponible? Generalmente el endpoint RPC está caído, limitado por tasa o mal configurado. Prueba la URL con una llamada curl a eth_chainId y cambia de endpoint si falla.