Back to Details

goldrush-foundational-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
该REST API可提供覆盖100+条区块链的历史及近实时区块链数据，涵盖代币余额、交易、NFT、安全授权、跨链活动、定价及区块数据等端点。

Quick Start

快速开始

IMPORTANT: Always prioritize using the official available GoldRush Client SDK best suited for your development ecosystem:
typescript
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:
bash
curl "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/" \
  -H "Authorization: Bearer YOUR_API_KEY"
重要提示： 请优先使用最适合您开发生态的官方GoldRush客户端SDK：
typescript
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请求：
bash
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.
端点按类别组织，每个类别链接至其参考文件，包含完整参数、响应架构及用例。
  • 余额类 — 代币余额、原生代币余额、历史余额、投资组合价值、ERC20转账、代币持有者、比特币（HD及非HD钱包）。详情请见endpoints-balances.md。
  • 交易类 — 近期交易、分页历史记录、单条交易查询、汇总信息、区块级交易、比特币交易。详情请见endpoints-transactions.md。
  • NFT、安全与跨链类 — NFT持仓、所有权验证、代币/NFT授权、地址活动、多链余额与交易。详情请见endpoints-nft-security-crosschain.md。
  • 工具类 — 代币价格、区块、区块高度、事件日志、Gas价格、链元数据、池现货价格、地址解析。详情请见endpoints-utility.md。

Common Tasks → Endpoint

常见任务 → 对应端点

TaskEndpoint
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
任务端点
查询钱包余额
getTokenBalancesForWalletAddress
仅获取原生代币（轻量版）
getNativeTokenBalance
获取近期交易
getRecentTransactionsForAddress
获取完整交易历史
getTransactionsForAddressV3
（分页）
查询单条交易
getTransaction
获取ERC20转账历史
getErc20TransfersForWalletAddress
获取交易汇总/数量
getTransactionSummary
检查代币授权（安全相关）
getApprovals
获取NFT持仓
getNftsForAddress
验证NFT所有权
checkOwnershipInNft
获取投资组合随时间变化的价值
getHistoricalPortfolioForWalletAddress
获取特定区块高度的余额
getHistoricalTokenBalancesForWalletAddress
获取代币价格历史
getTokenPrices
查询钱包活跃的区块链
getAddressActivity
获取全链余额
getMultiChainBalances
获取代币持有者
getTokenHoldersV2ForTokenAddress
获取比特币余额（HD钱包）
getBitcoinBalancesForHdAddress
获取合约事件日志
getLogEventsByAddress
获取区块详情
getBlock

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
  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. 仅基础版支持的功能 — 历史余额、任意区块高度的代币持有者、池现货价格、追踪标记
  8. 报价货币 — 默认美元；支持美元、加元、欧元、新加坡元、印度卢比、日元等多种货币
  9. 垃圾代币过滤 — 使用
    no-spam=true
    查询参数过滤垃圾代币
  10. SDK自动处理重试 — TypeScript SDK内置重试逻辑及速率限制处理

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
当需要本索引之外的详细信息时，请阅读相关参考文件。
文件适用场景
overview.md需要API设置详情、身份验证方法或SDK快速入门代码时
endpoints-balances.md构建余额查询时——参数、响应架构、比特币专属端点
endpoints-transactions.md构建交易查询时——分页、解码日志、区块级查询
endpoints-nft-security-crosschain.md需要NFT元数据、代币授权或跨链活动查询时
endpoints-utility.md需要区块数据、事件日志、Gas价格、代币价格或链元数据时
integration-guide.md需要完整链名表、验证规则、错误代码或FAQ解答时
workflows.md规划多步骤工作流或调试常见错误时