Skip to main content

​
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: 
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

TaskEndpoint
Check wallet balancegetTokenBalancesForWalletAddress
Get native token only (lightweight)getNativeTokenBalance
Get recent transactionsgetRecentTransactionsForAddress
Get full transaction historygetTransactionsForAddressV3 (paginated)
Look up a single transactiongetTransaction
Get ERC20 transfer historygetErc20TransfersForWalletAddress
Get transaction summary/countgetTransactionSummary
Check token approvals (security)getApprovals
Get NFT holdingsgetNftsForAddress
Verify NFT ownershipcheckOwnershipInNft
Get portfolio value over timegetHistoricalPortfolioForWalletAddress
Get balance at a specific blockgetHistoricalTokenBalancesForWalletAddress
Get token price historygetTokenPrices
Find which chains a wallet is active ongetAddressActivity
Get balances across all chainsgetMultiChainBalances
Get token holdersgetTokenHoldersV2ForTokenAddress
Get Bitcoin balance (HD wallet)getBitcoinBalancesForHdAddress
Get contract event logsgetLogEventsByAddress
Get block detailsgetBlock

​
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.
FileWhen to read
overview.mdNeed API setup details, authentication methods, or SDK quickstart code
endpoints-balances.mdBuilding a balance query — parameters, response schema, Bitcoin-specific endpoints
endpoints-transactions.mdBuilding a transaction query — pagination, decoded logs, block-level queries
endpoints-nft-security-crosschain.mdNeed NFT metadata, token approvals, or cross-chain activity lookups
endpoints-utility.mdNeed block data, event logs, gas prices, token prices, or chain metadata
integration-guide.mdNeed full chain names table, validation rules, error codes, or FAQ answers
workflows.mdPlanning a multi-step workflow or debugging a common error