What does the Gnosis API expose, and how do you connect to it?

The Gnosis API is the JSON-RPC surface that Gnosis Chain nodes expose to applications. If you are wiring a wallet, a Safe-based treasury tool, a payments backend, or an indexer to Gnosis, this is the interface you call. This page gives you the chain settings, a working request, the methods that matter for typical Gnosis workloads, and a way to decide what kind of endpoint you actually need.

Which Gnosis endpoint fits your workload?

Before copying any URL, match the endpoint type to what your application does. Gnosis traffic is often a mix of light reads and heavier log queries, and the right choice depends on volume and consistency needs rather than on the chain itself.

If your calls are occasional and read-only, a shared endpoint is a reasonable starting point. If you poll receipts in a loop, scan logs across large block ranges, or need consistent response times under load, plan for a managed or dedicated setup. You can review RPC pricing and the Gnosis network page to see what is available before you commit.

Gnosis Chain settings at a glance

These are the values you enter into a wallet, a Hardhat or Foundry config, or an ethers/viem provider. They are stable and safe to hardcode in client configuration.

Gnosis uses xDAI as its gas token, which is a meaningful difference from chains that pay gas in a volatile asset. For payment and payroll use cases this keeps fee accounting simpler, but it also means your users need xDAI on hand before they can send transactions.

Wallet network configuration

Most EVM wallets accept a custom network entry. The fields map directly to the table above:

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

Note that 0x64 is the hexadecimal form of chain ID 100. Wallets that expect hex will reject the decimal value, so keep both forms handy when debugging connection errors.

Making your first Gnosis API request

Every Gnosis API call is a JSON-RPC POST. The shape is the same as any EVM chain, so existing tooling works without modification once the endpoint and chain ID are set.

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

A successful response returns the latest block height as a hex string. From there, the common next calls are eth_getBalance for xDAI balances, eth_call for contract reads, and eth_getLogs for event history.

In JavaScript, the same request through a provider library looks like this:

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));

Passing the chain ID explicitly helps libraries detect a mismatch early instead of silently querying the wrong network.

Methods that matter for Gnosis workloads

Gnosis is EVM-compatible, so the standard method set applies. In practice, a few methods carry most of the traffic:

• eth_call — read contract state without a transaction. This is the backbone of Safe balance checks, token metadata reads, and most dashboard queries.
• eth_getLogs — retrieve events. Log queries are the most common source of rate pressure because a single request can span thousands of blocks.
• eth_getTransactionReceipt — confirm whether a submitted transaction landed. Payment services poll this heavily.
• eth_sendRawTransaction — broadcast signed transactions. This is where endpoint reliability matters most, since a dropped broadcast can leave a user waiting.
• eth_estimateGas and eth_gasPrice — size transactions and set fees before signing.
• eth_getCode and eth_getStorageAt — inspect deployed contracts and raw state, useful for tooling and debugging.

If you rely on live event streams rather than polling, check whether your chosen endpoint supports WebSocket subscriptions such as eth_subscribe for new heads or logs. Not every shared endpoint exposes WebSocket transport, so confirm this before designing around subscriptions.

Debugging common Gnosis API failures

Most Gnosis API problems fall into a small number of categories. The fastest path is to match the symptom to the cause before changing anything else.

A useful first diagnostic is a single eth_chainId call. If it does not return 0x64, your client is pointed at the wrong network and nothing downstream will behave as expected.

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

When a shared endpoint is not enough

Shared public endpoints are convenient and fine for development, prototypes, and low-volume reads. They become a bottleneck when your application depends on consistent throughput or long-running queries.

The signals that you have outgrown a shared endpoint are usually operational rather than dramatic: log queries that need to be split into many smaller calls, receipt polling that occasionally times out, or a spike in 429 responses during peak hours. At that point the question is not whether Gnosis works, but whether your access pattern needs reserved capacity.

A dedicated node gives your application its own Gnosis node rather than a slice of a shared pool. That matters for indexers scanning wide log ranges, relayers that need stable WebSocket connections, and services that cannot tolerate another tenant's traffic affecting their response times. OnFinality provides both managed RPC API access and dedicated node infrastructure, so you can start on a shared endpoint and move to reserved capacity without changing your application code beyond the URL. See dedicated nodes for how that transition works.

Operational checklist before you ship

A short checklist catches most production issues before users do:

1. Confirm chain ID 100 in your provider config, not just in the URL.
2. Add a fallback endpoint so a single provider outage does not take your app down.
3. Batch independent reads where your library supports it, rather than firing them sequentially.
4. Cap eth_getLogs block ranges and paginate instead of requesting everything at once.
5. Add exponential backoff for 429 and 5xx responses.
6. Log the raw JSON-RPC error code alongside your application error, so you can tell a client bug from an endpoint limit.
7. For WebSocket use, implement reconnect and resubscribe rather than assuming a persistent connection.

If you are still deciding between endpoint types, the RPC provider selection guide walks through the evaluation criteria in more depth, and supported RPC networks shows where Gnosis sits alongside the rest of the catalog.

Key Takeaways

• The Gnosis API is standard EVM JSON-RPC, so existing ethers, viem, Hardhat, and Foundry tooling works once chain ID 100 is set.
• Gnosis pays gas in xDAI, which simplifies fee accounting but requires users to hold xDAI before transacting.
• eth_call, eth_getLogs, and eth_getTransactionReceipt drive most Gnosis traffic; log queries are the usual source of rate pressure.
• A shared endpoint is fine for development and light reads; dedicated nodes make sense for indexers, relayers, and high-volume backends.
• Always verify eth_chainId returns 0x64 when debugging unexpected behavior.

Frequently Asked Questions

Is the Gnosis API the same as the Ethereum API?

At the protocol level, yes. Gnosis is EVM-compatible, so it uses the same JSON-RPC method names and request format. The differences are the chain ID (100), the gas token (xDAI), and the specific contracts and state on the network.

What is the Gnosis Chain ID?

Gnosis Chain uses chain ID 100, which is 0x64 in hexadecimal. Wallets and libraries that expect hex will reject the decimal form.

Do I need an API key to use the Gnosis API?

It depends on the endpoint. Public endpoints are typically open and rate-limited, while managed and dedicated endpoints use an API key tied to your account so your traffic gets its own capacity and support path.

Can I use WebSockets with Gnosis?

Gnosis supports WebSocket subscriptions at the node level, but not every shared endpoint exposes WebSocket transport. Confirm availability with your provider before designing around eth_subscribe.

Why do my eth_getLogs calls fail on Gnosis?

Large block ranges are the most common cause. Split the range into smaller windows and paginate through results rather than requesting a wide span in one call.

How do I move from a public endpoint to a dedicated Gnosis node?

In most cases you change the endpoint URL and add your API key. Application logic stays the same because the JSON-RPC interface does not change. Review RPC pricing and the Gnosis network page to plan the move.