Configuración de Base RPC en MetaMask: Chain ID, URL de RPC y soluciones de conexión

Qué hace MetaMask cuando agregas una red personalizada

Cuando agregas una red personalizada en MetaMask, la billetera almacena cinco campos: NetworkName, URL de RPC, Chain ID, símbolo de moneda y URL del explorador de bloques. No son solo etiquetas. La URL de RPC es el endpoint HTTP que MetaMask usará para cada solicitud JSON-RPC, y el Chain ID es el valor que MetaMask espera que ese endpoint reporte. Según la documentación de soporte de MetaMask, la billetera valida la conexión antes de guardar la red.

El paso de validación es una llamada JSON-RPC. MetaMask envía eth_chainId a la URL de RPC y compara el chain ID hexadecimal devuelto con el valor decimal que ingresaste. Por lo general, también llama a net_version como verificación secundaria. Si alguna de las llamadas falla, expira o devuelve un chain ID que no coincide, MetaMask cancela el guardado y muestra un error. La especificación JSON-RPC de Ethereum define eth_chainId como el método que devuelve el chain ID de la red actual, por eso las billeteras dependen de él para la detección de red.

Esto significa que la URL de RPC debe ser accesible desde el contexto del navegador, debe hablar JSON-RPC 2.0 y debe devolver el chain ID que escribiste. Una URL que funciona en una terminal pero bloquea orígenes del navegador seguirá fallando en MetaMask. Una URL que devuelve un chain ID válido para una red diferente también fallará. La billetera no está probando si el endpoint es rápido o confiable; está probando si el endpoint es la red que afirmas que es.

• NetworkName: una etiqueta almacenada localmente, no se envía al endpoint RPC.
• URL de RPC: el endpoint HTTP para todas las llamadas JSON-RPC.
• Chain ID: el valor decimal que MetaMask espera que eth_chainId devuelva en hexadecimal.
• Símbolo de moneda: solo para visualización; no afecta las llamadas RPC.
• URL del explorador de bloques: se usa para enlazar transacciones, no para validación.

Parámetros correctos de la red Base para mainnet y Sepolia

Base mainnet usa el chain ID 8453, que en hexadecimal es 0x2105. La moneda nativa es ETH. Base Sepolia, la testnet, usa el chain ID 84532, que en hexadecimal es 0x14a34. Estos valores están documentados en la documentación de Base. El chain ID debe coincidir exactamente porque MetaMask compara el valor decimal que ingresas con el valor hexadecimal devuelto por eth_chainId.

Para la URL de RPC, puedes usar un endpoint público o un endpoint de proveedor. Los endpoints públicos son convenientes para uso interactivo ligero, pero son compartidos y a menudo tienen límites de tasa. Los endpoints de proveedor, como los descritos en la página Endpoint RPC de Base (RPC Assistant), están diseñados para volúmenes de solicitudes más altos y pueden incluir soporte WebSocket. Si necesitas transporte WebSocket, consulta la guía Conexiones WebSocket RPC de Base.

La URL del explorador de bloques es opcional pero útil. Para Base mainnet, el explorador suele ser https://basescan.org. Para Base Sepolia, es https://sepolia.basescan.org. Estos no afectan la validación RPC, pero hacen que los enlaces de transacciones funcionen correctamente.

• Base mainnet: Chain ID 8453 (0x2105), moneda ETH, URL de RPC de un proveedor o endpoint público.
• Base Sepolia: Chain ID 84532 (0x14a34), moneda ETH, URL de RPC de un proveedor o endpoint público.
• Explorador de bloques mainnet: https://basescan.org
• Explorador de bloques Sepolia: https://sepolia.basescan.org

Los cinco errores de conexión y sus causas raíz

La mayoría de los fallos de conexión de Base a MetaMask se agrupan en cinco clases. El primero es 'No se pudo obtener el chain ID'. Esto ocurre cuando la URL de RPC es incorrecta, está caída o restringida. El endpoint puede estar fuera de línea, puede requerir una clave API o puede rechazar la solicitud antes de que llegue a la capa JSON-RPC. MetaMask no puede continuar porque no puede confirmar la cadena.

El segundo es una discrepancia de chain ID. La billetera muestra una cadena, pero el endpoint devuelve otra. Esto ocurre cuando pegas una URL de RPC de una red diferente, como Ethereum mainnet o una testnet, mientras ingresas el chain ID de Base. MetaMask compara el chain ID hexadecimal devuelto con tu entrada decimal y se niega a guardar si difieren.

El tercero es un bloqueo por CORS o referrer. Las billeteras basadas en navegador llaman a la URL de RPC desde un origen web. Si el endpoint no incluye el encabezado Access-Control-Allow-Origin adecuado, el navegador bloquea la respuesta antes de que MetaMask pueda leerla. Esto a menudo parece un error de red genérico en la billetera, pero la consola del navegador muestra un fallo de CORS.

El cuarto es la limitación de tasa HTTP 429. Los endpoints públicos aplican cuotas de solicitudes. MetaMask sondea la URL de RPC con frecuencia, especialmente cuando la billetera está abierta y rastreando transacciones pendientes. Un endpoint público que funciona para una dapp con llamadas ocasionales aún puede devolver 429 bajo el sondeo de la billetera. El artículo Límites de tasa y confiabilidad de Base RPC cubre el comportamiento de las cuotas con más detalle.

El quinto es una página de error HTML o un interstitial de proxy devuelto en lugar de JSON. Esto ocurre cuando un proxy, portal cautivo o gateway mal configurado intercepta la solicitud y devuelve HTML. MetaMask espera una respuesta JSON-RPC 2.0 y no puede analizar HTML, por lo que reporta un fallo de fetch. La solución es verificar que el endpoint devuelva JSON con el encabezado Content-Type correcto.

• No se pudo obtener el chain ID: URL de RPC incorrecta, caída o restringida.
• Discrepancia de chain ID: el endpoint devuelve un chain ID diferente al ingresado.
• Bloqueo por CORS/referrer: el endpoint no permite el origen del navegador.
• HTTP 429: endpoint público limitado por tasa bajo el sondeo de la billetera.
• HTML en lugar de JSON: un proxy o gateway intermedio rompe el parseo.

Probar el endpoint de forma independiente con curl

Antes de cambiar algo en MetaMask, prueba la URL de RPC fuera de la billetera. Una sola solicitud POST con curl al endpoint con eth_chainId te dice si el endpoint es accesible y qué chain ID devuelve. Para Base mainnet, el resultado debe ser 0x2105. Si obtienes un error HTTP, un cuerpo HTML o un valor hexadecimal diferente, el problema es el endpoint, no MetaMask.

La especificación JSON-RPC 2.0 requiere un campo jsonrpc establecido en "2.0", un method, params y un id. El siguiente comando curl envía una solicitud mínima. Reemplaza la URL con tu endpoint candidato de Base. La bandera -i incluye los encabezados de respuesta para que puedas inspeccionar el Content-Type y cualquier encabezado CORS.

• Resultado esperado para Base mainnet: {"jsonrpc":"2.0","id":1,"result":"0x2105"}
• Resultado esperado para Base Sepolia: {"jsonrpc":"2.0","id":1,"result":"0x14a34"}
• Verifica el estado HTTP: se espera 200; 401, 403 o 429 indican problemas de acceso o cuota.
• Verifica Content-Type: application/json; text/html indica un proxy o página de error.

curl -i -X POST https://mainnet.base.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

Detectar fallos de CORS con un fetch desde la consola del navegador

Los fallos de CORS son invisibles en curl porque curl no aplica políticas de origen del navegador. Para reproducir lo que ve MetaMask, abre la consola de tu navegador en cualquier página y ejecuta un fetch contra la URL de RPC candidata. Si el endpoint no permite tu origen, el navegador bloqueará la respuesta y registrará un error de CORS. Este es el mismo fallo que encuentra MetaMask cuando llama al endpoint desde el contexto de la extensión.

El siguiente fragmento envía la misma solicitud eth_chainId desde el navegador. Si tiene éxito, verás la respuesta JSON. Si falla, la consola mostrará un error de CORS o de red. Esta prueba distingue un endpoint que funciona del lado del servidor de uno que funciona en una billetera de navegador.

• Si la consola muestra un error de CORS, el endpoint no permite tu origen del navegador.
• Si la consola muestra un error de red, el endpoint puede ser inalcanzable o estar bloqueado por una extensión.
• Si la consola muestra un error de parseo JSON, el endpoint devolvió HTML o contenido no JSON.

fetch('https://mainnet.base.org', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_chainId',
    params: []
  })
})
  .then(res => res.json())
  .then(data => console.log('Chain ID:', data.result))
  .catch(err => console.error('Fetch failed:', err));

Sonda ejecutable en Node.js para eth_chainId, net_version y eth_blockNumber

Una sonda más exhaustiva verifica tres métodos: eth_chainId, net_version y eth_blockNumber. Esto te da el chain ID, el network ID y el último número de bloque. El script a continuación imprime PASS o FAIL para cada método, junto con el estado HTTP y los primeros bytes del cuerpo de la respuesta. Utiliza la API fetch integrada disponible en Node.js 18 y posteriores.

Ejecuta este script con node probe.js https://tu-endpoint-base. Reemplaza el argumento de URL con tu endpoint candidato. El script sale con un código distinto de cero si alguna verificación falla, lo que lo hace utilizable en CI o para una verificación rápida en terminal.

• eth_chainId debe devolver 0x2105 para Base mainnet.
• net_version debe devolver 8453 para Base mainnet.
• eth_blockNumber debe devolver un número de bloque hexadecimal que aumenta con el tiempo.
• Cualquier FAIL indica que el endpoint no es adecuado para MetaMask.

const url = process.argv[2];
if (!url) {
  console.error('Usage: node probe.js <RPC_URL>');
  process.exit(1);
}

const methods = ['eth_chainId', 'net_version', 'eth_blockNumber'];

async function probe(method) {
  const body = JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method,
    params: []
  });
  try {
    const res = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body
    });
    const text = await res.text();
    const firstBytes = text.slice(0, 80).replace(/\n/g, ' ');
    let parsed;
    try {
      parsed = JSON.parse(text);
    } catch (e) {
      console.log(`FAIL ${method} | HTTP ${res.status} | non-JSON body: ${firstBytes}`);
      return false;
    }
    if (parsed.error) {
      console.log(`FAIL ${method} | HTTP ${res.status} | error: ${JSON.stringify(parsed.error)}`);
      return false;
    }
    console.log(`PASS ${method} | HTTP ${res.status} | result: ${parsed.result}`);
    return true;
  } catch (err) {
    console.log(`FAIL ${method} | network error: ${err.message}`);
    return false;
  }
}

(async () => {
  let allPass = true;
  for (const method of methods) {
    const ok = await probe(method);
    if (!ok) allPass = false;
  }
  process.exit(allPass ? 0 : 1);
})();

Tabla de resultados reproducible para tu propio endpoint

Usa la tabla a continuación para registrar tus propias mediciones. Completa una fila por cada endpoint que pruebes. El objetivo es comparar endpoints objetivamente e identificar qué clase de error aplica. No confíes en la memoria; registra el estado HTTP, el chain ID devuelto, si CORS pasó y la solución que aplicaste.

Si estás probando varios endpoints, ejecuta la sonda de Node.js y el fetch del navegador para cada uno. La tabla deja claro qué endpoint es adecuado para MetaMask y cuál requiere un enfoque diferente, como un endpoint de proveedor o una conexión WebSocket.

• Endpoint: la URL de RPC completa que probaste.
• Estado HTTP: el código de estado devuelto por la sonda.
• eth_chainId: el valor hexadecimal devuelto o el mensaje de error.
• ¿CORS ok?: sí si el fetch del navegador tuvo éxito, no si falló.
• Clase de error: una de las cinco clases descritas anteriormente.
• Solución aplicada: el cambio que hiciste, como cambiar de endpoint o eliminar y volver a agregar la red.

Por qué MetaMask almacena en caché entradas de red rotas

MetaMask almacena las configuraciones de redes personalizadas localmente. Si agregas una red con una URL de RPC rota, la billetera puede conservar esa entrada incluso después de corregir la URL en otro lugar. En algunos casos, la solución requiere eliminar la red por completo y volver a agregarla con los parámetros correctos. Este es un comportamiento documentado en la documentación de soporte de MetaMask.

El comportamiento de caché significa que editar la URL de RPC en el lugar puede no ser suficiente. Si ves errores persistentes después de cambiar la URL, elimina la red de la lista de redes de MetaMask y vuelve a agregarla. Esto obliga a la billetera a volver a ejecutar la validación de eth_chainId contra el nuevo endpoint.

Esto también explica por qué una red que funcionaba antes puede fallar de repente. Si el endpoint cambió su política de CORS o comenzó a limitar la tasa, MetaMask puede seguir teniendo la configuración antigua en caché. Eliminar y volver a agregar la red es la forma más limpia de restablecer el estado de validación.

• MetaMask almacena redes personalizadas localmente y puede no actualizar la validación automáticamente.
• Si los errores persisten después de editar la URL de RPC, elimina y vuelve a agregar la red.
• Volver a agregar fuerza una nueva llamada a eth_chainId contra el nuevo endpoint.

Limitaciones de las soluciones del lado del cliente y los endpoints públicos

Ninguna solución del lado del cliente sustituye a un endpoint confiable. Si estás usando un endpoint público de Base para algo más que uso interactivo ligero, eventualmente alcanzarás límites de tasa o restricciones de CORS. MetaMask sondea la URL de RPC con frecuencia, y un endpoint público que funciona para una dapp con llamadas ocasionales aún puede devolver 429 bajo el sondeo de la billetera. El artículo Límites de tasa y confiabilidad de Base RPC explica la mecánica de las cuotas.

Para aplicaciones en producción, usa un endpoint de proveedor con un nivel de servicio documentado. La página Precios de RPC describe los planes disponibles, y la página Servicio de API cubre la oferta más amplia de API. Si necesitas transporte WebSocket para suscripciones, la guía Conexiones WebSocket RPC de Base cubre esa configuración.

Otra limitación es que la validación de MetaMask solo verifica eth_chainId y net_version. No prueba eth_blockNumber ni verifica que el endpoint esté sincronizado. Un endpoint puede pasar la validación y aún devolver datos de bloques obsoletos. Para aplicaciones que dependen de la finalidad, consulta el artículo Finalidad de Base: bloques safe y finalized.

• Los endpoints públicos son compartidos y tienen límites de tasa; no son adecuados para sondeo de alta frecuencia.
• La validación de MetaMask no prueba la altura de bloque ni el estado de sincronización.
• Se recomiendan endpoints de proveedor con SLA documentados para uso en producción.
• El transporte WebSocket requiere un endpoint y una configuración separados.

Lista de verificación para fallos de conexión persistentes

Si has probado el endpoint con curl y el fetch del navegador, y MetaMask sigue fallando, revisa esta lista de verificación. Comienza confirmando que el chain ID que ingresaste coincide con el valor hexadecimal devuelto por eth_chainId. Para Base mainnet, el valor decimal es 8453 y el valor hexadecimal es 0x2105. Para Base Sepolia, el valor decimal es 84532 y el valor hexadecimal es 0x14a34.

Luego, verifica si el endpoint requiere una clave API. Algunos endpoints de proveedor devuelven 401 o 403 sin una clave. Si estás usando un endpoint público, verifica si tiene un límite de tasa y si lo estás alcanzando. Si la consola del navegador muestra un error de CORS, el endpoint no permite tu origen; cambia a un endpoint de proveedor que admita orígenes del navegador.

Si el endpoint devuelve HTML en lugar de JSON, es posible que estés detrás de un proxy o portal cautivo. Prueba el endpoint desde una red diferente o desactiva cualquier extensión de proxy. Finalmente, si nada más funciona, elimina la red de MetaMask y vuelve a agregarla con los parámetros correctos. Para un recorrido relacionado sobre errores de obtención de chain ID, consulta Tiempos de espera y reintentos de Base RPC.

• Verifica el chain ID: 8453 (0x2105) para Base mainnet, 84532 (0x14a34) para Base Sepolia.
• Verifica los requisitos de clave API: 401 o 403 indican un endpoint restringido.
• Verifica los límites de tasa: 429 indica agotamiento de cuota.
• Verifica CORS: los errores en la consola del navegador indican restricciones de origen.
• Verifica respuestas HTML: un proxy o portal cautivo puede estar interceptando.
• Elimina y vuelve a agregar la red si los errores persisten después de corregir el endpoint.

Próximos pasos: elegir un endpoint RPC de Base confiable

Una vez que hayas confirmado el chain ID correcto y probado tu endpoint, el siguiente paso es elegir un endpoint que se ajuste a tu uso. Para uso interactivo ligero, un endpoint público puede ser suficiente. Para cualquier cosa que implique sondeo frecuente, transacciones automatizadas o dapps en producción, un endpoint de proveedor es la mejor opción. La página Endpoint RPC de Base (RPC Assistant) te ayuda a comparar opciones.

Si estás construyendo sobre Base y necesitas acceso HTTP y WebSocket, revisa la guía Conexiones WebSocket RPC de Base. Para planificar límites de tasa, consulta Límites de tasa y confiabilidad de Base RPC. Para consideraciones de finalidad, consulta Finalidad de Base: bloques safe y finalized.

Para una visión más amplia de temas de RPC, visita el centro de aprendizaje de OnFinality. Si estás listo para pasar de un endpoint público a un servicio gestionado, las páginas Precios de RPC y Servicio de API describen las opciones disponibles. La conclusión clave es que la validación de MetaMask es un punto de partida, no una garantía de confiabilidad; elige un endpoint que se ajuste a tu volumen de solicitudes y necesidades de transporte.

• Usa endpoints públicos solo para uso interactivo ligero.
• Usa endpoints de proveedor para producción, automatización o sondeo de alta frecuencia.
• Considera el transporte WebSocket si necesitas suscripciones.
• Revisa la documentación de finalidad si tu aplicación depende de la confirmación de bloques.