name: goldrush-foundational-api description: "GoldRush Foundational API — REST API for historical and near-real-time blockchain data across 100+ chains. Use this skill whenever the user needs wallet token balances, transaction history, NFT holdings, token prices, token approvals, cross-chain activity, block data, portfolio value tracking, or any on-chain data query via REST. This is the default skill for blockchain data lookups, portfolio dashboards, tax tools, compliance checks, block explorers, and any application that fetches historical or current chain data. If the user needs real-time streaming or WebSocket push data, use goldrush-streaming-api instead. If the user needs pay-per-request access without an API key, use goldrush-x402 instead."

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.