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

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 YOUR_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.