GoldRush Foundational API

REST API providing historical and near-real-time blockchain data across 100+ chains. Endpoints cover token balances, transactions, NFTs, security approvals, cross-chain activity, pricing, and block data.

Quick Start

IMPORTANT: Always prioritize using the official available GoldRush Client SDK best suited for your development ecosystem:

• TypeScript Client SDK

import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient("YOUR_API_KEY");

const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet",
  "demo.eth"
);

if (!resp.error) {
  console.log(resp.data.items);
} else {
  console.error(resp.error_message);
}

Install: npm install @covalenthq/client-sdk

Raw HTTP:

curl "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoint Categories

Endpoints are organized into categories. Each links to its reference file with full parameters, response schemas, and use cases.

• Balances — token balances, native balances, historical balances, portfolio value, ERC20 transfers, token holders, Bitcoin (HD and non-HD). See endpoints-balances.md.
• Transactions — recent transactions, paginated history, single transaction lookup, summaries, block-level transactions, Bitcoin transactions. See endpoints-transactions.md.
• NFT, Security & Cross-Chain — NFT holdings, ownership verification, token/NFT approvals, address activity, multi-chain balances and transactions. See endpoints-nft-security-crosschain.md.
• Utility — token prices, blocks, block heights, event logs, gas prices, chain metadata, pool spot prices, address resolution. See endpoints-utility.md.

Common Tasks → Endpoint

Critical Rules

1. Chain names are case-sensitive — use eth-mainnet, not ethereum or Eth-Mainnet
2. Authentication — Authorization: Bearer YOUR_API_KEY (HTTPS only)
3. Pagination is 0-indexed — first page is 0, 100 items per page
4. Always check resp.error before accessing resp.data
5. Token balances are strings — divide by 10^contract_decimals for human-readable values
6. ENS/domain resolution — pass vitalik.eth directly as the wallet address
7. Foundational-only features — historical balances, token holders at any block, pool spot prices, tracing flags
8. Quote currency — defaults to USD; supported: USD, CAD, EUR, SGD, INR, JPY, and more
9. Spam filtering — use no-spam=true query parameter to filter spam tokens
10. SDK handles retries — the TypeScript SDK has built-in retry logic and rate limit handling

Reference Files

Read the relevant reference file when you need details beyond what this index provides.