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("<GOLDRUSH_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 <GOLDRUSH_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

Task	Endpoint
Check wallet balance	`getTokenBalancesForWalletAddress`
Get native token only (lightweight)	`getNativeTokenBalance`
Get recent transactions	`getRecentTransactionsForAddress`
Get full transaction history	`getTransactionsForAddressV3` (paginated)
Look up a single transaction	`getTransaction`
Get ERC20 transfer history	`getErc20TransfersForWalletAddress`
Get transaction summary/count	`getTransactionSummary`
Check token approvals (security)	`getApprovals`
Get NFT holdings	`getNftsForAddress`
Verify NFT ownership	`checkOwnershipInNft`
Get portfolio value over time	`getHistoricalPortfolioForWalletAddress`
Get balance at a specific block	`getHistoricalTokenBalancesForWalletAddress`
Get token price history	`getTokenPrices`
Find which chains a wallet is active on	`getAddressActivity`
Get balances across all chains	`getMultiChainBalances`
Get token holders	`getTokenHoldersV2ForTokenAddress`
Get Bitcoin balance (HD wallet)	`getBitcoinBalancesForHdAddress`
Get contract event logs	`getLogEventsByAddress`
Get block details	`getBlock`

Critical Rules

Chain names are case-sensitive - use eth-mainnet, not ethereum or Eth-Mainnet
Authentication - Authorization: Bearer <GOLDRUSH_API_KEY> (HTTPS only)
Pagination is 0-indexed - first page is 0, 100 items per page
Always check resp.error before accessing resp.data
Token balances are strings - divide by 10^contract_decimals for human-readable values
ENS/domain resolution - pass vitalik.eth directly as the wallet address
Foundational-only features - historical balances, token holders at any block, pool spot prices, tracing flags
Quote currency - defaults to USD; supported: USD, CAD, EUR, SGD, INR, JPY, and more
Spam filtering - use no-spam=true query parameter to filter spam tokens
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.

File	When to read
overview.md	Need API setup details, authentication methods, or SDK quickstart code
endpoints-balances.md	Building a balance query - parameters, response schema, Bitcoin-specific endpoints
endpoints-transactions.md	Building a transaction query - pagination, decoded logs, block-level queries
endpoints-nft-security-crosschain.md	Need NFT metadata, token approvals, or cross-chain activity lookups
endpoints-utility.md	Need block data, event logs, gas prices, token prices, or chain metadata
integration-guide.md	Need full chain names table, validation rules, error codes, or FAQ answers
workflows.md	Planning a multi-step workflow or debugging a common error

Learn about GoldRush

Components

SKILL

GoldRush Foundational API

Quick Start

Endpoint Categories

Common Tasks → Endpoint

Critical Rules

Reference Files

​GoldRush Foundational API

​Quick Start

​Endpoint Categories

​Common Tasks → Endpoint

​Critical Rules

​Reference Files

GoldRush Foundational API

Quick Start

Endpoint Categories

Common Tasks → Endpoint

Critical Rules

Reference Files