API de Polygon MATIC: ¿Qué deben saber los desarrolladores?

Guía rápida de decisión: ¿Qué API de Polygon necesitas?

Antes de sumergirte en endpoints y SDK, es útil mapear el panorama de las API de Polygon. El término "API de Polygon MATIC" puede significar varias cosas diferentes, y elegir la incorrecta desperdicia tiempo de ingeniería.

Para la mayoría de los desarrolladores de dApps, el endpoint JSON-RPC puro es la base. Te da control total y funciona con cualquier herramienta de Ethereum (ethers, viem, web3.js). Si necesitas datos indexados o funciones específicas de pagos, agregarás una API especializada encima.

Si estás construyendo una aplicación de producción, querrás un proveedor de RPC confiable. OnFinality ofrece endpoints RPC de Polygon administrados con soporte HTTP y WebSocket, y puedes comparar precios para ver si un nodo dedicado se ajusta a tu carga de trabajo.

¿Qué es la API de Polygon MATIC?

Polygon (anteriormente Matic Network) es una cadena de prueba de participación compatible con Ethereum. La "API de Polygon MATIC" generalmente se refiere a las interfaces para interactuar con esta cadena. El núcleo es la API JSON-RPC, que es idéntica a la de Ethereum, por lo que cualquier biblioteca de Ethereum funciona sin problemas.

Históricamente, MATIC era el token nativo utilizado para gas. Después de la actualización de POL, POL es ahora el token nativo, pero muchos documentos y herramientas todavía hacen referencia a MATIC. La API en sí no cambia: todavía estás enviando transacciones y consultando el estado.

También hay API de nivel superior:

• Matic.js: un SDK heredado para interactuar con los contratos del puente de Polygon. Todavía está en los documentos, pero se está eliminando gradualmente.
• API de indexación: servicios como Bitquery que proporcionan endpoints GraphQL o REST para datos históricos, saldos de tokens y análisis.
• API de pagos: servicios como Chaingateway que abstraen la gestión de nodos y proporcionan webhooks para depósitos.

Configuración de la cadena Polygon de un vistazo

Al configurar tu aplicación, necesitas el ID de cadena y la URL RPC correctos. Aquí están los ajustes oficiales para la red principal de Polygon:

Para la red de prueba, la red de prueba Polygon Amoy usa el ID de cadena 80002 y la URL RPC pública https://polygon-amoy.api.onfinality.io/public. Puedes encontrar más detalles en la página de red de Polygon.

Cómo conectarse a Polygon con JSON-RPC

Puedes usar cualquier biblioteca compatible con Ethereum. Aquí hay un ejemplo usando ethers.js para leer un saldo y enviar una transacción:

const { ethers } = require("ethers");

const provider = new ethers.JsonRpcProvider("https://polygon.api.onfinality.io/public");

async function getBalance(address) {
  const balance = await provider.getBalance(address);
  console.log(`Balance: ${ethers.formatEther(balance)} POL`);
}

async function sendTransaction(signer, to, amount) {
  const tx = await signer.sendTransaction({
    to,
    value: ethers.parseEther(amount),
  });
  await tx.wait();
  console.log(`Tx hash: ${tx.hash}`);
}

Para llamadas JSON-RPC puras, puedes usar curl:

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

Esto devuelve el número de bloque más reciente, confirmando que tu endpoint está activo.

Uso de Matic.js para operaciones de puente

Matic.js es el SDK heredado para interactuar con el puente de Polygon. Todavía está documentado, pero Polygon Labs recomienda alternativas más nuevas para mover dinero. Si estás manteniendo código existente, aquí tienes un ejemplo rápido:

const { POSClient, use } = require("@maticnetwork/maticjs");
const { Web3ClientPlugin } = require("@maticnetwork/maticjs-web3");
const HDWalletProvider = require("@truffle/hdwallet-provider");

use(Web3ClientPlugin);

const posClient = new POSClient();
await posClient.init({
  network: "mainnet",
  version: "v1",
  parent: {
    provider: new HDWalletProvider(privateKey, "https://ethereum-rpc.example.com"),
    defaultConfig: { from: userAddress },
  },
  child: {
    provider: new HDWalletProvider(privateKey, "https://polygon.api.onfinality.io/public"),
    defaultConfig: { from: userAddress },
  },
});

const erc20 = posClient.erc20("<token-address>");
const balance = await erc20.getBalance(userAddress);

Ten en cuenta que Matic.js está obsoleto para nuevos proyectos. Para interacciones modernas con el puente, considera usar la interfaz de usuario oficial del puente de Polygon o una API de pagos.

API de indexación para saldos e historial

Si necesitas consultar saldos históricos o titulares de tokens, una API de indexación como Bitquery puede ser más eficiente que escanear bloques tú mismo. Por ejemplo, para obtener el saldo nativo de POL de una dirección:

query {
  EVM(network: matic, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0x..." }
        }
      }
    ) {
      Currency { Symbol }
      Balance { Amount }
    }
  }
}

Estas API son útiles para paneles de análisis, pistas de auditoría y aplicaciones de billetera. Por lo general, requieren una clave de API y tienen límites de uso.

Elegir entre RPC público, administrado y dedicado

Para aplicaciones de producción, el endpoint público no es lo suficientemente confiable. Tienes tres opciones principales:

OnFinality proporciona RPC de Polygon administrado que maneja problemas de infraestructura como equilibrio de carga y conmutación por error. Para necesidades de alto rendimiento o archivo, un nodo dedicado podría valer el costo.

Errores comunes y solución de problemas

• Discrepancia de ID de cadena: asegúrate de que tu billetera use el ID de cadena 137 para la red principal, no 80001 (antigua Mumbai testnet) ni 80002 (Amoy).
• Límite de velocidad: los endpoints públicos a menudo limitan la velocidad. Si ves errores 429, cambia a un proveedor administrado.
• Desconexiones de WebSocket: para actualizaciones en tiempo real, usa WebSocket pero implementa lógica de reconexión.
• MATIC vs POL: algunas herramientas todavía esperan MATIC. Consulta la documentación de tu biblioteca para conocer el símbolo correcto.

Conclusiones clave

• La API de Polygon MATIC es principalmente JSON-RPC, compatible con herramientas de Ethereum.
• Elige la capa de API adecuada: RPC puro para control, API de indexación para análisis, API de pagos para flujos de stablecoin.
• Usa el ID de cadena correcto (137) y un proveedor de RPC confiable para producción.
• OnFinality ofrece RPC de Polygon administrado con soporte HTTP y WebSocket.

Preguntas frecuentes

¿Cuál es la diferencia entre MATIC y POL?

MATIC era el token nativo original. En 2024, Polygon actualizó a POL, que ahora sirve como token de gas y token de staking. La API y el ID de cadena siguen siendo los mismos.

¿Puedo usar bibliotecas de Ethereum con Polygon?

Sí, Polygon es compatible con EVM, por lo que ethers.js, viem y web3.js funcionan sin modificación. Solo apúntalos a un endpoint RPC de Polygon.

¿El endpoint RPC público de Polygon es gratuito?

Sí, el endpoint público https://polygon.api.onfinality.io/public es gratuito, pero tiene límites de velocidad. Para producción, considera un plan RPC administrado.

¿Cómo obtengo POL de testnet para Amoy?

Puedes usar el grifo de Amoy, que está enlazado desde la página de red de Polygon.

¿Para qué se usa Matic.js?

Matic.js es un SDK heredado para interactuar con el puente de Polygon. Está obsoleto para nuevos proyectos, pero el código existente puede usarlo.

¿OnFinality admite WebSocket para Polygon?

Sí, el endpoint de Polygon de OnFinality admite tanto HTTP como WebSocket. Consulta la página de red para más detalles.

¿Cómo elijo entre un RPC administrado y un nodo dedicado?

Si necesitas alto rendimiento, datos de archivo o configuración personalizada, un nodo dedicado puede ser mejor. Para la mayoría de las aplicaciones, un RPC administrado ofrece un buen equilibrio entre costo y confiabilidad. Consulta nuestra guía de selección de proveedores de RPC para más información.

¿Cuáles son los límites de velocidad para el endpoint público?

Los endpoints públicos están sujetos a límites de velocidad para garantizar un uso justo. Para límites más altos, regístrate para obtener una clave de API gratuita en OnFinality.

¿Puedo usar Polygon con viem?

Sí, viem admite Polygon de forma nativa. Puedes crear un cliente con createPublicClient({ chain: polygon, transport: http("https://polygon.api.onfinality.io/public") }).

¿Dónde puedo encontrar la lista completa de redes compatibles?

Visita la página de redes compatibles para ver todas las cadenas que OnFinality admite.