goldrush-foundational-api
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
| 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, notethereumorEth-Mainnet - Authentication —
Authorization: Bearer YOUR_API_KEY(HTTPS only) - Pagination is 0-indexed — first page is
0, 100 items per page - Always check
resp.errorbefore accessingresp.data - Token balances are strings — divide by
10^contract_decimalsfor human-readable values - ENS/domain resolution — pass
vitalik.ethdirectly 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=truequery 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 |
More from covalenthq/goldrush-agent-skills
goldrush-cli
GoldRush CLI — terminal-first blockchain data tool with MCP support for Claude Desktop and Claude Code. Use this skill whenever the user wants to query blockchain data from the command line, stream DEX pairs or wallet activity in a terminal, set up GoldRush as an MCP tool provider, or run quick one-off queries without writing code (e.g., 'check a wallet balance', 'what's the gas price', 'search for a token'). Also use this when the user mentions 'goldrush' CLI commands, 'npx @covalenthq/goldrush-cli', or MCP integration with GoldRush. The CLI is the fastest path for ad-hoc blockchain lookups from the terminal. If the user needs programmatic API access in an application, use goldrush-foundational-api or goldrush-streaming-api instead. If the user needs pay-per-request access without an API key, use goldrush-x402 instead.
41goldrush-streaming-api
GoldRush Streaming API — real-time blockchain data via GraphQL subscriptions over WebSocket. Use this skill whenever the user needs live price feeds (OHLCV candles), real-time DEX pair monitoring (new pairs, liquidity updates), wallet activity streaming, decoded swap/transfer events, token search, trader PnL analysis, or any sub-second latency blockchain event push. This is the right skill for trading bots, live dashboards, alerting systems, copy-trading, DEX sniping, and real-time analytics. Also covers one-time GraphQL queries for token discovery and profitability analysis. If the user needs historical data, batch queries, or paginated REST results, use goldrush-foundational-api instead. If the user needs pay-per-request access without an API key, use goldrush-x402 instead.
40goldrush-x402
GoldRush x402 — pay-per-request blockchain data access using the x402 protocol (HTTP 402 Payment Required). Use this skill whenever the user is building an AI agent that needs blockchain data without API keys, wants wallet-based micropayments for on-chain data, needs autonomous or no-account access to the GoldRush API, mentions the x402 protocol, or wants no-signup/no-onboarding blockchain data access. This is the right skill for autonomous agents, serverless applications, and prototyping without onboarding. Provides access to 60+ Foundational API endpoints through a transparent reverse proxy with stablecoin payments on Base. If the user needs a traditional API key with monthly billing, use goldrush-foundational-api instead. If the user needs real-time streaming data via WebSocket, use goldrush-streaming-api instead.
34