Skip to main content

Documentation Index

Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
GoldRush JSON-RPC Quickstart

​
Header-based authentication

API keys are sent as an Authorization: Bearer <key> header, never in the URL. The same GoldRush API key works across all GoldRush products.

​
Per-library setup

See the rendered reference for copy-paste examples. The pattern in each library:
  • ethers v6: new ethers.FetchRequest(url) + .setHeader("Authorization", ...), pass to new ethers.JsonRpcProvider(req)
  • viem: http(url, { fetchOptions: { headers: { Authorization: ... } } })
  • web3.js: new Web3.providers.HttpProvider(url, { headers: [{ name, value }] })
  • web3.py: Web3.HTTPProvider(url, request_kwargs={"headers": {...}})
  • curl: -H "Authorization: Bearer $GOLDRUSH_API_KEY"

​
Endpoint shape

https://rpc.goldrushdata.com/v1/{chain}
Replace {chain} with one of: eth-mainnet, matic-mainnet, bsc-mainnet, arbitrum-mainnet, base-mainnet, hyperevm-mainnet, megaeth-mainnet, monad-mainnet, tempo-mainnet.

​
1. Get a GoldRush API key

If you already have a GoldRush key for any other GoldRush product (Foundational, Streaming, Pipeline, Hyperliquid, x402), you can use it as-is. JSON-RPC uses the same key. If not, sign up at goldrush.dev to get one. 
export GOLDRUSH_API_KEY="cqt_..."
Warning: Never commit your API key to source control. Use environment variables or a secrets manager.

​
2. Pick a chain

The endpoint shape is: 
https://rpc.goldrushdata.com/v1/{chain}
Replace {chain} with one of the supported chain slugs. For Ethereum mainnet, that’s eth-mainnet.

​
3. Make a request

curl
curl https://rpc.goldrushdata.com/v1/eth-mainnet \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  }'
ethers v6
import { ethers } from "ethers";

const url = "https://rpc.goldrushdata.com/v1/eth-mainnet";
const fetchReq = new ethers.FetchRequest(url);
fetchReq.setHeader("Authorization", `Bearer ${process.env.GOLDRUSH_API_KEY}`);

const provider = new ethers.JsonRpcProvider(fetchReq);
const block = await provider.getBlockNumber();
console.log("latest block:", block);
viem
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({
  chain: mainnet,
  transport: http("https://rpc.goldrushdata.com/v1/eth-mainnet", {
    fetchOptions: {
      headers: {
        Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`,
      },
    },
  }),
});

const block = await client.getBlockNumber();
console.log("latest block:", block);
web3.js
import { Web3 } from "web3";

const provider = new Web3.providers.HttpProvider(
  "https://rpc.goldrushdata.com/v1/eth-mainnet",
  {
    headers: [
      { name: "Authorization", value: `Bearer ${process.env.GOLDRUSH_API_KEY}` },
    ],
  }
);
const web3 = new Web3(provider);
const block = await web3.eth.getBlockNumber();
console.log("latest block:", block);
web3.py
from os import environ
from web3 import Web3

w3 = Web3(Web3.HTTPProvider(
    "https://rpc.goldrushdata.com/v1/eth-mainnet",
    request_kwargs={
        "headers": {
            "Authorization": f"Bearer {environ['GOLDRUSH_API_KEY']}",
        },
    },
))
print("latest block:", w3.eth.block_number)

​
4. Where to next

​
Authentication details

Header reference, error codes, key rotation tips.

​
Method reference

All 44 methods with parameters, returns, and code examples per chain.

​
Endpoint details

Archive, debug_*, trace_*, SLA.

​
Migration guides

Coming from Infura, Alchemy, or Ankr.
GoldRush JSON-RPC authenticates every request by an Authorization: Bearer HTTP header. Your API key never appears in the URL, keeping it out of server logs, browser history, screenshots, and error reports. This matches the pattern used across the rest of the GoldRush product family. The same GoldRush API key works across every GoldRush product: Foundational, Streaming, Pipeline, Hyperliquid, x402, and JSON-RPC. One key, every product.

​
The header

Authorization: Bearer cqt_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Content-Type: application/json is required: JSON-RPC payloads are always JSON.

​
Per-library setup

viem, ethers, web3.js, and web3.py all support custom request headers, but the boilerplate differs slightly between them. Copy whichever one applies.
ethers v6
import { ethers } from "ethers";

const url = "https://rpc.goldrushdata.com/v1/eth-mainnet";
const fetchReq = new ethers.FetchRequest(url);
fetchReq.setHeader("Authorization", `Bearer ${process.env.GOLDRUSH_API_KEY}`);

const provider = new ethers.JsonRpcProvider(fetchReq);
viem
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({
  chain: mainnet,
  transport: http("https://rpc.goldrushdata.com/v1/eth-mainnet", {
    fetchOptions: {
      headers: {
        Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`,
      },
    },
  }),
});
web3.js
import { Web3 } from "web3";

const provider = new Web3.providers.HttpProvider(
  "https://rpc.goldrushdata.com/v1/eth-mainnet",
  {
    headers: [
      { name: "Authorization", value: `Bearer ${process.env.GOLDRUSH_API_KEY}` },
    ],
  }
);
const web3 = new Web3(provider);
web3.py
from os import environ
from web3 import Web3

w3 = Web3(Web3.HTTPProvider(
    "https://rpc.goldrushdata.com/v1/eth-mainnet",
    request_kwargs={
        "headers": {
            "Authorization": f"Bearer {environ['GOLDRUSH_API_KEY']}",
        },
    },
))
curl
curl https://rpc.goldrushdata.com/v1/eth-mainnet \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

​
Error responses

Authentication and credit failures return the standard JSON-RPC error envelope with an HTTP status code matching the failure mode.
HTTPJSON-RPC codeMeaningResolution
401 Unauthorized-32001Missing or malformed Authorization headerAdd the Authorization: Bearer header
403 Forbidden-32002Key is valid but lacks JSON-RPC entitlementContact support to enable JSON-RPC
402 Payment Required-32003Insufficient creditsTop up your credit balance
429 Too Many Requests-32005Rate limit exceededBack off and retry after Retry-After
Example failure body: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "missing or invalid Authorization header"
  }
}

​
Rotating keys

Generate a new key in the GoldRush dashboard, update your environment variable, and revoke the old one. There is no per-product key rotation: rotating once cycles the key for every GoldRush product.
Tip: For zero-downtime rotation, set both the old and new key as accepted in your config, deploy with the new key, then revoke the old key once traffic has cut over.

​
Quickstart

Make your first call.

​
Pricing

Per-method credit rates for the Edge tier.