goldrush-foundational-api

GoldRush 基础 API

REST API，提供覆盖 100 多条区块链的历史和近实时区块链数据。端点涵盖代币余额、交易、NFT、安全授权、跨链活动、价格和区块数据。

快速开始

重要： 请始终优先使用最适合你的开发生态系统的官方 GoldRush Client SDK：

• 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);
}

安装： npm install @covalenthq/client-sdk

原始 HTTP：

curl "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/" \
  -H "Authorization: Bearer YOUR_API_KEY"

端点类别

端点按类别组织。每个类别都链接到对应的参考文件，其中包含完整参数、响应架构和用例。

• 余额 — 代币余额、原生余额、历史余额、投资组合价值、ERC20 转账、代币持有者、Bitcoin（HD 和非 HD）。请参阅 endpoints-balances.md。
• 交易 — 最近交易、分页历史记录、单笔交易查询、摘要、区块级交易、Bitcoin 交易。请参阅 endpoints-transactions.md。
• NFT、安全与跨链 — NFT 持有情况、所有权验证、代币/NFT 授权、地址活动、多链余额和交易。请参阅 endpoints-nft-security-crosschain.md。
• 实用工具 — 代币价格、区块、区块高度、事件日志、Gas 价格、链元数据、池现货价格、地址解析。请参阅 endpoints-utility.md。

常见任务 → 端点

任务	端点
检查钱包余额	getTokenBalancesForWalletAddress
仅获取原生代币（轻量）	getNativeTokenBalance
获取最近交易	getRecentTransactionsForAddress
获取完整交易历史	getTransactionsForAddressV3（分页）
查询单笔交易	getTransaction
获取 ERC20 转账历史	getErc20TransfersForWalletAddress
获取交易摘要/数量	getTransactionSummary
检查代币授权（安全）	getApprovals
获取 NFT 持有情况	getNftsForAddress
验证 NFT 所有权	checkOwnershipInNft
获取一段时间内的投资组合价值	getHistoricalPortfolioForWalletAddress
获取指定区块的余额	getHistoricalTokenBalancesForWalletAddress
获取代币价格历史	getTokenPrices
查找钱包在哪些链上活跃	getAddressActivity
获取所有链上的余额	getMultiChainBalances
获取代币持有者	getTokenHoldersV2ForTokenAddress
获取 Bitcoin 余额（HD 钱包）	getBitcoinBalancesForHdAddress
获取合约事件日志	getLogEventsByAddress
获取区块详情	getBlock

关键规则

1. 链名称区分大小写 — 使用 eth-mainnet，不要使用 ethereum 或 Eth-Mainnet
2. 身份验证 — Authorization: Bearer YOUR_API_KEY（仅限 HTTPS）
3. 分页索引从 0 开始 — 第一页为 0，每页 100 项
4. 访问 resp.data 前，务必检查 resp.error
5. 代币余额为字符串 — 除以 10^contract_decimals 可得到便于阅读的数值
6. ENS/域名解析 — 直接将 vitalik.eth 作为钱包地址传入
7. 仅限基础 API 的功能 — 历史余额、任意区块的代币持有者、池现货价格、追踪标志
8. 报价货币 — 默认为 USD；支持：USD、CAD、EUR、SGD、INR、JPY 等
9. 垃圾信息过滤 — 使用 no-spam=true 查询参数过滤垃圾代币
10. SDK 处理重试 — TypeScript SDK 内置重试逻辑和速率限制处理

参考文件

如果需要了解本索引未提供的详细信息，请阅读相关参考文件。

文件	阅读时机
overview.md	需要了解 API 设置详情、身份验证方法或 SDK 快速入门代码时
endpoints-balances.md	构建余额查询时——参数、响应架构、Bitcoin 专属端点
endpoints-transactions.md	构建交易查询时——分页、解码后的日志、区块级查询
endpoints-nft-security-crosschain.md	需要查询 NFT 元数据、代币授权或跨链活动时
endpoints-utility.md	需要查询区块数据、事件日志、Gas 价格、代币价格或链元数据时
integration-guide.md	需要完整的链名称表、验证规则、错误代码或常见问题解答时
workflows.md	规划多步骤工作流或排查常见错误时