¿Qué expone la API de Gnosis y cómo te conectas a ella?

La API de Gnosis es la superficie JSON-RPC que los nodos de Gnosis Chain exponen a las aplicaciones. Si estás conectando una billetera, una herramienta de tesorería basada en Safe, un backend de pagos o un indexador a Gnosis, esta es la interfaz que llamas. Esta página te proporciona la configuración de la cadena, una solicitud funcional, los métodos que importan para las cargas de trabajo típicas de Gnosis y una forma de decidir qué tipo de endpoint necesitas realmente.

¿Qué endpoint de Gnosis se adapta a tu carga de trabajo?

Antes de copiar cualquier URL, haz coincidir el tipo de endpoint con lo que hace tu aplicación. El tráfico de Gnosis suele ser una mezcla de lecturas ligeras y consultas de registros más pesadas, y la elección correcta depende del volumen y las necesidades de consistencia, no de la cadena en sí.

Si tus llamadas son ocasionales y de solo lectura, un endpoint compartido es un punto de partida razonable. Si sondeas recibos en un bucle, escaneas registros en rangos de bloques grandes o necesitas tiempos de respuesta consistentes bajo carga, planifica una configuración gestionada o dedicada. Puedes revisar Precios de RPC y la página de red de Gnosis para ver qué está disponible antes de comprometerte.

Configuración de Gnosis Chain de un vistazo

Estos son los valores que ingresas en una billetera, una configuración de Hardhat o Foundry, o un proveedor de ethers/viem. Son estables y seguros para codificar en la configuración del cliente.

Gnosis usa xDAI como su token de gas, lo que marca una diferencia significativa con las cadenas que pagan gas en un activo volátil. Para casos de uso de pagos y nómina, esto simplifica la contabilidad de comisiones, pero también significa que tus usuarios necesitan tener xDAI a mano antes de poder enviar transacciones.

Configuración de red de la billetera

La mayoría de las billeteras EVM aceptan una entrada de red personalizada. Los campos se asignan directamente a la tabla anterior:

{
  "chainId": "0x64",
  "chainName": "Gnosis",
  "nativeCurrency": { "name": "xDAI", "symbol": "XDAI", "decimals": 18 },
  "rpcUrls": ["https://gnosis.api.onfinality.io/public"],
  "blockExplorerUrls": ["https://gnosisscan.io"]
}

Ten en cuenta que 0x64 es la forma hexadecimal del ID de cadena 100. Las billeteras que esperan hexadecimal rechazarán el valor decimal, así que mantén ambas formas a mano al depurar errores de conexión.

Cómo hacer tu primera solicitud a la API de Gnosis

Cada llamada a la API de Gnosis es un POST JSON-RPC. La forma es la misma que en cualquier cadena EVM, por lo que las herramientas existentes funcionan sin modificaciones una vez configurados el endpoint y el ID de cadena.

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

Una respuesta exitosa devuelve la altura del último bloque como una cadena hexadecimal. A partir de ahí, las siguientes llamadas comunes son eth_getBalance para saldos en xDAI, eth_call para lecturas de contratos y eth_getLogs para el historial de eventos.

En JavaScript, la misma solicitud a través de una biblioteca de proveedor se ve así:

import { JsonRpcProvider, formatEther } from "ethers";

const provider = new JsonRpcProvider(
  "https://gnosis.api.onfinality.io/public",
  { chainId: 100, name: "gnosis" }
);

const block = await provider.getBlockNumber();
const balance = await provider.getBalance("0xYourAddressHere");
console.log(block, formatEther(balance));

Pasar el ID de cadena explícitamente ayuda a las bibliotecas a detectar un desajuste temprano en lugar de consultar silenciosamente la red incorrecta.

Métodos que importan para las cargas de trabajo en Gnosis

Gnosis es compatible con EVM, por lo que se aplica el conjunto de métodos estándar. En la práctica, unos pocos métodos concentran la mayor parte del tráfico:

• eth_call — lee el estado del contrato sin una transacción. Es la columna vertebral de las verificaciones de saldo de Safe, las lecturas de metadatos de tokens y la mayoría de las consultas de panel.
• eth_getLogs — recupera eventos. Las consultas de registros son la fuente más común de presión de velocidad porque una sola solicitud puede abarcar miles de bloques.
• eth_getTransactionReceipt — confirma si una transacción enviada se confirmó. Los servicios de pago sondean esto intensamente.
• eth_sendRawTransaction — transmite transacciones firmadas. Aquí es donde la confiabilidad del endpoint importa más, ya que una transmisión fallida puede dejar a un usuario esperando.
• eth_estimateGas y eth_gasPrice — dimensionan transacciones y establecen tarifas antes de firmar.
• eth_getCode y eth_getStorageAt — inspeccionan contratos desplegados y estado sin procesar, útil para herramientas y depuración.

Si dependes de flujos de eventos en vivo en lugar de sondeo, verifica si el endpoint elegido admite suscripciones WebSocket como eth_subscribe para nuevos encabezados o registros. No todos los endpoints compartidos exponen transporte WebSocket, así que confírmalo antes de diseñar en torno a suscripciones.

Depuración de fallos comunes de la API de Gnosis

La mayoría de los problemas de la API de Gnosis se dividen en unas pocas categorías. La ruta más rápida es hacer coincidir el síntoma con la causa antes de cambiar cualquier otra cosa.

Un primer diagnóstico útil es una sola llamada eth_chainId. Si no devuelve 0x64, tu cliente apunta a la red incorrecta y nada aguas abajo se comportará como se espera.

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

Cuándo un endpoint compartido no es suficiente

Los endpoints públicos compartidos son convenientes y adecuados para desarrollo, prototipos y lecturas de bajo volumen. Se convierten en un cuello de botella cuando tu aplicación depende de un rendimiento consistente o consultas de larga duración.

Las señales de que has superado un endpoint compartido suelen ser operativas más que dramáticas: consultas de registros que deben dividirse en muchas llamadas más pequeñas, sondeo de recibos que ocasionalmente expira o un pico en respuestas 429 durante las horas pico. En ese momento, la pregunta no es si Gnosis funciona, sino si tu patrón de acceso necesita capacidad reservada.

Un nodo dedicado le da a tu aplicación su propio nodo de Gnosis en lugar de una porción de un grupo compartido. Eso importa para indexadores que escanean rangos amplios de registros, relayers que necesitan conexiones WebSocket estables y servicios que no pueden tolerar que el tráfico de otro inquilino afecte sus tiempos de respuesta. OnFinality proporciona tanto acceso gestionado a la API RPC como infraestructura de nodo dedicada, para que puedas comenzar en un endpoint compartido y pasar a capacidad reservada sin cambiar el código de tu aplicación más allá de la URL. Consulta nodos dedicados para saber cómo funciona esa transición.

Lista de verificación operativa antes de lanzar

Una breve lista de verificación detecta la mayoría de los problemas de producción antes que los usuarios:

1. Confirma el ID de cadena 100 en la configuración de tu proveedor, no solo en la URL.
2. Agrega un endpoint de respaldo para que una caída de un solo proveedor no derribe tu aplicación.
3. Agrupa lecturas independientes donde tu biblioteca lo admita, en lugar de ejecutarlas secuencialmente.
4. Limita los rangos de bloques de eth_getLogs y pagina en lugar de solicitar todo a la vez.
5. Agrega retroceso exponencial para respuestas 429 y 5xx.
6. Registra el código de error JSON-RPC sin procesar junto con el error de tu aplicación, para que puedas distinguir un error del cliente de un límite del endpoint.
7. Para uso de WebSocket, implementa reconexión y resuscripción en lugar de asumir una conexión persistente.

Si aún estás decidiendo entre tipos de endpoint, la guía de selección de proveedor de RPC recorre los criterios de evaluación con más profundidad, y redes RPC compatibles muestra dónde se ubica Gnosis junto al resto del catálogo.

Puntos clave

• La API de Gnosis es JSON-RPC EVM estándar, por lo que las herramientas existentes de ethers, viem, Hardhat y Foundry funcionan una vez configurado el ID de cadena 100.
• Gnosis paga gas en xDAI, lo que simplifica la contabilidad de comisiones pero requiere que los usuarios tengan xDAI antes de realizar transacciones.
• eth_call, eth_getLogs y eth_getTransactionReceipt impulsan la mayor parte del tráfico de Gnosis; las consultas de registros son la fuente habitual de presión de velocidad.
• Un endpoint compartido está bien para desarrollo y lecturas ligeras; los nodos dedicados tienen sentido para indexadores, relayers y backends de alto volumen.
• Siempre verifica que eth_chainId devuelva 0x64 al depurar comportamientos inesperados.

Preguntas frecuentes

¿La API de Gnosis es lo mismo que la API de Ethereum?

A nivel de protocolo, sí. Gnosis es compatible con EVM, por lo que utiliza los mismos nombres de métodos JSON-RPC y formato de solicitud. Las diferencias son el ID de cadena (100), el token de gas (xDAI) y los contratos y estado específicos en la red.

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

Gnosis Chain usa el ID de cadena 100, que es 0x64 en hexadecimal. Las billeteras y bibliotecas que esperan hexadecimal rechazarán la forma decimal.

¿Necesito una clave API para usar la API de Gnosis?

Depende del endpoint. Los endpoints públicos suelen estar abiertos y limitados por velocidad, mientras que los endpoints gestionados y dedicados usan una clave API vinculada a tu cuenta para que tu tráfico obtenga su propia capacidad y ruta de soporte.

¿Puedo usar WebSockets con Gnosis?

Gnosis admite suscripciones WebSocket a nivel de nodo, pero no todos los endpoints compartidos exponen transporte WebSocket. Confirma la disponibilidad con tu proveedor antes de diseñar en torno a eth_subscribe.

¿Por qué fallan mis llamadas a eth_getLogs en Gnosis?

Los rangos de bloques grandes son la causa más común. Divide el rango en ventanas más pequeñas y pagina a través de los resultados en lugar de solicitar un intervalo amplio en una sola llamada.

¿Cómo paso de un endpoint público a un nodo dedicado de Gnosis?

En la mayoría de los casos, cambias la URL del endpoint y agregas tu clave API. La lógica de la aplicación sigue siendo la misma porque la interfaz JSON-RPC no cambia. Revisa Precios de RPC y la página de red de Gnosis para planificar el cambio.