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:
CODEBLOCK0
Install: INLINECODE0
Raw HTTP:
CODEBLOCK1
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 | INLINECODE1 |
| 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
- 1. Chain names are case-sensitive — use
eth-mainnet, not ethereum or INLINECODE22 - 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 INLINECODE26 - 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.
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 |
GoldRush 基础 API
提供覆盖 100+ 条链的历史及近实时区块链数据的 REST API。接口涵盖代币余额、交易、NFT、安全授权、跨链活动、定价及区块数据。
快速开始
重要提示： 始终优先使用最适合您开发环境的官方 GoldRush 客户端 SDK：
typescript
import { GoldRushClient } from @covalenthq/client-sdk;
const client = new GoldRushClient(YOURAPIKEY);
const resp = await client.BalanceService.getTokenBalancesForWalletAddress(
eth-mainnet,
demo.eth
);
if (!resp.error) {
console.log(resp.data.items);
} else {
console.error(resp.error_message);
}
安装： npm install @covalenthq/client-sdk
原始 HTTP 请求：
bash
curl https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/ \
-H Authorization: Bearer YOURAPIKEY
接口分类
接口按类别组织。每个类别链接至对应的参考文件，包含完整参数、响应模式及使用案例。
常见任务 → 对应接口
| 任务 | 接口 |
|---|
| 检查钱包余额 | getTokenBalancesForWalletAddress |
| 仅获取原生代币（轻量级） |
getNativeTokenBalance |
| 获取近期交易 | getRecentTransactionsForAddress |
| 获取完整交易历史 | getTransactionsForAddressV3（分页） |
| 查询单笔交易 | getTransaction |
| 获取 ERC20 转账历史 | getErc20TransfersForWalletAddress |
| 获取交易摘要/计数 | getTransactionSummary |
| 检查代币授权（安全） | getApprovals |
| 获取 NFT 持仓 | getNftsForAddress |
| 验证 NFT 所有权 | checkOwnershipInNft |
| 获取投资组合历史价值 | getHistoricalPortfolioForWalletAddress |
| 获取特定区块的余额 | getHistoricalTokenBalancesForWalletAddress |
| 获取代币价格历史 | getTokenPrices |
| 查找钱包活跃的链 | getAddressActivity |
| 获取跨链余额 | getMultiChainBalances |
| 获取代币持有者 | getTokenHoldersV2ForTokenAddress |
| 获取比特币余额（HD 钱包） | getBitcoinBalancesForHdAddress |
| 获取合约事件日志 | getLogEventsByAddress |
| 获取区块详情 | getBlock |
关键规则
- 1. 链名称区分大小写 — 使用 eth-mainnet，而非 ethereum 或 Eth-Mainnet
- 身份验证 — Authorization: Bearer YOURAPIKEY（仅 HTTPS）
- 分页从 0 开始 — 第一页为 0，每页 100 条
- 访问 resp.data 前始终检查 resp.error
- 代币余额为字符串 — 除以 10^contract_decimals 获得可读数值
- ENS/域名解析 — 可直接传入 vitalik.eth 作为钱包地址
- 基础版专属功能 — 历史余额、任意区块的代币持有者、池现货价格、追踪标记
- 报价货币 — 默认为 USD；支持：USD、CAD、EUR、SGD、INR、JPY 等
- 垃圾过滤 — 使用 no-spam=true 查询参数过滤垃圾代币
- SDK 自动处理重试 — TypeScript SDK 内置重试逻辑和速率限制处理
参考文件
当需要本索引未提供的详细信息时，请阅读相关参考文件。
构建余额查询 — 参数、响应模式、比特币专用接口 |
|
endpoints-transactions.md | 构建交易查询 — 分页、解码日志、区块级查询 |
|
endpoints-nft-security-crosschain.md | 需要 NFT 元数据、代币授权或跨链活动查询 |
|
endpoints-utility.md | 需要区块数据、事件日志、Gas 费用、代币价格或链元数据 |
|
integration-guide.md | 需要完整链名称表、验证规则、错误码或常见问题解答 |
|
workflows.md | 规划多步骤工作流或调试常见错误 |
