Documentation

Quick start

ChainRPC is a standard JSON-RPC endpoint. Use it with any client — ethers.js, viem, web3.js, MetaMask, Hardhat, Foundry.

Endpoint format

https://{chain}.chainrpc.net/{your_api_key}

Replace {chain} with any supported chain subdomain and {your_api_key} with your key.

Example: ethers.js

import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider(
  'https://base.chainrpc.net/rpk_YOUR_KEY'
);
const block = await provider.getBlockNumber();
console.log(block);

Example: viem

import { createPublicClient, http } from 'viem';
import { base } from 'viem/chains';

const client = createPublicClient({
  chain: base,
  transport: http('https://base.chainrpc.net/rpk_YOUR_KEY'),
});

Example: curl

curl -X POST https://base.chainrpc.net/rpk_YOUR_KEY \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Example: MetaMask

Settings → Networks → Add Network → paste:

https://base.chainrpc.net/rpk_YOUR_KEY

Supported chains

Chain	Subdomain	Chain ID
Ethereum	ethereum.chainrpc.net	1
Base	base.chainrpc.net	8453
Arbitrum One	arbitrum.chainrpc.net	42161
Optimism	optimism.chainrpc.net	10
Polygon PoS	polygon.chainrpc.net	137
BNB Chain	bsc.chainrpc.net	56
Avalanche C-Chain	avalanche.chainrpc.net	43114
Gnosis	gnosis.chainrpc.net	100
Ethereum Sepolia	sepolia.chainrpc.net	11155111
zkSync Era	zksync.chainrpc.net	324
Linea	linea.chainrpc.net	59144
Scroll	scroll.chainrpc.net	534352
Blast	blast.chainrpc.net	81457
Mantle	mantle.chainrpc.net	5000
Polygon zkEVM	polygon-zkevm.chainrpc.net	1101
Mode	mode.chainrpc.net	34443
Zora	zora.chainrpc.net	7777777
Celo	celo.chainrpc.net	42220
Ethereum Sepolia	sepolia.chainrpc.net	11155111
Base Sepolia	base-sepolia.chainrpc.net	84532

Authentication

Your API key goes in the URL path. No headers needed.

POST https://base.chainrpc.net/rpk_abc123def456...

All standard JSON-RPC methods are supported: eth_blockNumber, eth_call, eth_sendRawTransaction, eth_getLogs, etc.

Rate limits

Tier	Requests/day	Requests/sec	Overflow	Price
Free	25,000	3	Blocked (429)	$0
Growth	500,000	30	$10 / million	$29/mo
Pro	5,000,000	100	$5 / million	$99/mo

Paid tiers are never blocked. When you exceed your included requests, overflow is charged from your approved USDC/USDT balance.

Response headers

X-RateLimit-Limit: 25000
X-RateLimit-Remaining: 18402
X-RateLimit-Reset: 1713052800
X-Chain: base
X-Cache: HIT
X-Overflow: true  ← only present when over included limit

Billing

Paid subscriptions use USDC or USDT on Base (chain ID 8453).

1. Link your wallet address to your key
2. Approve our billing contract for the desired amount
3. We pull your subscription monthly + overflow charges
4. Revoke approval anytime to cancel — no forms, no emails

Your USDC/USDT stays in your wallet until we pull it. You remain in full control.

Cancel

Three ways to stop paying:

• Revoke the approval in your wallet
• Move USDC/USDT out (pull will fail)
• Let the allowance run out

If a pull fails, your key reverts to free tier. No penalty, no debt.

Caching

ChainRPC caches responses for common methods. Cache hits return in <2ms.

Method	TTL
eth_chainId	24 hours
net_version	24 hours
eth_getCode	24 hours
eth_getTransactionReceipt	24 hours
eth_blockNumber	2 seconds
eth_gasPrice	5 seconds
eth_call	5 seconds
eth_getBalance	10 seconds
eth_getLogs	30 seconds
eth_sendRawTransaction	Never cached

The X-Cache: HIT or X-Cache: MISS header indicates whether the response came from cache.

Errors

HTTP	Meaning
200	Success (check JSON-RPC error field for RPC-level errors)
400	Unknown chain (check subdomain)
401	Invalid API key
429	Rate limited (free tier) or burst limit exceeded
503	Upstream chain node unavailable
504	Upstream timeout (30s)