Acceso a la API de Celo: Configuración de la cadena, métodos y modos de fallo

La API de Celo es la interfaz JSON-RPC que tu aplicación utiliza para comunicarse con Celo Mainnet. Si buscaste "api de celo", probablemente necesites una de tres cosas: la configuración de cadena correcta para agregar Celo a una billetera, un endpoint funcional para enviar tu primera solicitud, o una forma de depurar por qué falla una solicitud. Esta página responde a las tres, y luego te ayuda a decidir si un endpoint compartido es suficiente o si tu carga de trabajo necesita un nodo Celo dedicado.

Celo es una Layer 1 compatible con EVM, por lo que la mayoría de tus herramientas de Ethereum funcionan sin modificaciones. Las diferencias que importan son el ID de cadena, el símbolo de la moneda nativa y los métodos específicos de Celo relacionados con monedas de tarifas y abstracción de gas. Si aciertas con eso, el resto es JSON-RPC estándar.

Configuración de la cadena de un vistazo

Antes de escribir cualquier código, confirma los parámetros de la red. Estos son los valores que ingresas en una billetera, una configuración de Hardhat o una definición de cadena de viem.

Si estás agregando Celo a una billetera, usa el nombre de la red y el ID de cadena exactamente como se muestra. Un ID de cadena incorrecto es la razón más común por la que una billetera se niega a firmar o una dApp informa "red incorrecta".

Para un endpoint gestionado que puedes usar en desarrollo, OnFinality expone una URL RPC pública de Celo. Para tráfico de producción, revisa Precios de RPC y la página de la red Celo para elegir un plan que se ajuste a tu volumen de solicitudes.

Enviando tu primera solicitud a la API de Celo

Cada llamada a la API de Celo es una solicitud POST con un cuerpo JSON que contiene jsonrpc, method, params e id. Comienza con eth_chainId para confirmar que estás conectado a la red correcta, luego eth_blockNumber para verificar que el nodo está sincronizado.

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

La respuesta devuelve el ID de cadena en hexadecimal. Para Celo Mainnet, eso es 0xa4ec, que es 42220 en decimal. Si obtienes un valor diferente, estás apuntando a la red incorrecta.

Una vez que el ID de cadena es correcto, consulta un saldo y lee un contrato:

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

eth_call funciona de la misma manera que en Ethereum. Pasa la dirección to, los datos de función codificados y la etiqueta de bloque. La compatibilidad de Celo con EVM significa que las bibliotecas de codificación ABI como ethers y viem funcionan sin manejo especial.

Conexión desde JavaScript

Si prefieres una biblioteca cliente, tanto viem como ethers admiten Celo a través de una definición de cadena personalizada. El ejemplo a continuación usa viem y apunta al endpoint público.

import { createPublicClient, http, defineChain } from "viem";

const celo = defineChain({
  id: 42220,
  name: "Celo Mainnet",
  nativeCurrency: { name: "CELO", symbol: "CELO", decimals: 18 },
  rpcUrls: {
    default: { http: ["https://celo.api.onfinality.io/public"] },
  },
  blockExplorers: {
    default: { name: "Celoscan", url: "https://celoscan.io" },
  },
});

const client = createPublicClient({ chain: celo, transport: http() });

const blockNumber = await client.getBlockNumber();
const balance = await client.getBalance({ address: "0xYourAddressHere" });
console.log({ blockNumber, balance });

Para aplicaciones basadas en billetera, los mismos valores se ingresan en wallet_addEthereumChain. Mantén el ID de cadena y la URL RPC consistentes entre la configuración de tu billetera y tu backend para que los usuarios no vean solicitudes de cambio de red a mitad de sesión.

Cuándo un endpoint público es suficiente y cuándo no

Un endpoint público compartido es adecuado para desarrollo local, prototipos y rutas de lectura de bajo volumen. No es adecuado una vez que tienes usuarios reales, porque compartes el rendimiento con todos los demás y no puedes controlar los picos de latencia.

Usa esta tabla para decidir qué necesita realmente tu carga de trabajo.

Si no estás seguro de dónde encajas, comienza con la guía de selección de proveedor de RPC y luego compara planes en la página de precios. OnFinality ofrece tanto acceso a API RPC compartida como nodos dedicados para equipos que necesitan capacidad aislada.

Métodos específicos de Celo que vale la pena conocer

Debido a que Celo fue diseñado para pagos móviles, agrega métodos que Ethereum no tiene. Dos vale la pena conocerlos desde el principio.

eth_gasPrice devuelve un precio de gas, pero Celo también admite pagar gas en tokens ERC-20 aprobados. Si tu aplicación permite a los usuarios pagar tarifas en una stablecoin, interactuarás con el contrato de moneda de tarifa en lugar de solo con el saldo nativo de CELO. Lee la moneda de tarifa actual antes de construir una transacción y verifica que la cuenta tenga suficiente de ese token.

Celo también admite eth_getLogs con la misma forma de filtro que Ethereum. Si estás indexando eventos, mantén los rangos de bloques modestos y pagina. Las consultas de logs grandes sin límites son una causa común de tiempos de espera en cualquier proveedor, no solo en Celo.

Ruta de depuración para errores comunes de la API de Celo

La mayoría de los problemas de la API de Celo se dividen en un pequeño conjunto de categorías. Revísalos en orden.

Comienza cada sesión de depuración confirmando el ID de cadena. Si es correcto, verifica si la llamada fallida es una lectura o una escritura. Las lecturas generalmente fallan debido a parámetros mal formados o consultas demasiado grandes. Las escrituras generalmente fallan debido a problemas de nonce, gas o moneda de tarifa.

Para obtener una lista de verificación más amplia que se aplica a todas las redes, consulta la guía de endpoints RPC.

Ejecutar tu propio nodo versus usar una API de Celo gestionada

Algunos equipos consideran ejecutar su propio nodo Celo. Es una opción legítima, pero el costo operativo es fácil de subestimar. Necesitas aprovisionar hardware, mantener el cliente actualizado a través de actualizaciones de red, monitorear el crecimiento del disco y manejar la conmutación por error cuando el nodo se retrasa.

Una API de Celo gestionada elimina ese mantenimiento. Obtienes un endpoint y el proveedor se encarga de las actualizaciones, el monitoreo y la disponibilidad. La contrapartida es que dependes de la infraestructura del proveedor, por lo que la planificación de conmutación por error es importante.

Un punto medio práctico para aplicaciones en producción es usar un endpoint gestionado principal y mantener un segundo proveedor o un nodo autoalojado como respaldo. Configura tu cliente para reintentar contra el endpoint secundario cuando el primario devuelva errores repetidos. Esto es más simple que ejecutar dos nodos tú mismo y cubre el escenario de interrupción más común.

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

Antes de lanzar, confirma cada uno de estos puntos.

• El ID de cadena está codificado como 42220 y se valida al inicio.
• La URL RPC proviene de la configuración del entorno, no del código fuente.
• Tienes un endpoint de respaldo y una política de reintentos con retroceso exponencial.
• Las consultas de logs están paginadas y limitadas.
• Monitoreas las tasas de error y la latencia, no solo el tiempo de actividad.
• La lógica de moneda de tarifa está probada si los usuarios pagan gas en tokens.
• Has revisado Precios de RPC contra el volumen de solicitudes esperado.

Una sonda de monitoreo simple que verifica el ID de cadena y la altura del bloque detecta la mayoría de los problemas de conectividad antes que los usuarios:

async function healthCheck(url) {
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "eth_blockNumber",
      params: [],
      id: 1,
    }),
  });
  const data = await res.json();
  return parseInt(data.result, 16);
}

Ejecuta esto de forma programada y alerta cuando la altura del bloque deje de avanzar. Una altura estancada es una señal más clara que una solicitud HTTP fallida.

Puntos clave

• Celo es compatible con EVM, por lo que los métodos JSON-RPC estándar de Ethereum funcionan con el ID de cadena 42220.
• Siempre verifica eth_chainId antes de depurar cualquier otra cosa.
• Los endpoints públicos compartidos son adecuados para desarrollo; las cargas de trabajo en producción se benefician de capacidad dedicada.
• El modelo de moneda de tarifa de Celo agrega lógica de gas en tokens que las aplicaciones de Ethereum no tienen.
• Pagina eth_getLogs y monitorea la altura del bloque, no solo el estado HTTP.
• Planifica un endpoint de respaldo antes del lanzamiento, no después de un incidente.

Preguntas frecuentes

¿Qué es la API de Celo?

Es la interfaz JSON-RPC para Celo Mainnet. Envías solicitudes POST a un endpoint y recibes datos de la cadena o envías transacciones utilizando métodos EVM estándar.

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

Celo Mainnet usa el ID de cadena 42220, que es 0xa4ec en hexadecimal.

¿Puedo usar herramientas de Ethereum con Celo?

Sí. Debido a que Celo es compatible con EVM, bibliotecas como ethers, viem y Hardhat funcionan con una definición de cadena personalizada que establece el ID de cadena y la URL RPC.

¿Por qué mi solicitud a Celo devuelve un error 429?

Un 429 significa que estás siendo limitado por tasa, lo cual es común en endpoints públicos compartidos bajo carga. Cambiar a un plan dedicado o reducir las ráfagas de solicitudes generalmente lo resuelve.

¿Celo admite pagar gas en stablecoins?

Celo admite pagar gas en monedas de tarifa aprobadas. Tu aplicación necesita leer el contrato de moneda de tarifa y confirmar que la cuenta tiene suficiente de ese token antes de enviar una transacción.

¿Debería ejecutar mi propio nodo Celo?

Ejecuta tu propio nodo si necesitas control total o datos de archivo y puedes absorber el mantenimiento. De lo contrario, una API de Celo gestionada más un endpoint de respaldo suele ser más simple para aplicaciones en producción.

Si deseas pasar de un endpoint público a infraestructura gestionada, comienza en la página de la red Celo, compara planes de RPC y revisa la lista completa de redes RPC compatibles si operas en múltiples cadenas.