goldrush-foundational-api

GoldRush 基盤 API

100 以上のチェーンにわたる、履歴データおよびほぼリアルタイムのブロックチェーンデータを提供する REST API です。エンドポイントでは、トークン残高、トランザクション、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 を参照してください。
• ユーティリティ — トークン価格、ブロック、ブロック高、イベントログ、ガス価格、チェーンのメタデータ、プールのスポット価格、アドレスの解決。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. チェーン名は大文字と小文字を区別します — ethereum や Eth-Mainnet ではなく、eth-mainnet を使用してください
2. 認証 — Authorization: Bearer YOUR_API_KEY（HTTPS のみ）
3. ページネーションは 0 始まりです — 最初のページは 0 で、1 ページあたり 100 項目です
4. resp.data にアクセスする前に、必ず resp.error を確認してください
5. トークン残高は文字列です — 人間が読みやすい値にするには、10^contract_decimals で割ってください
6. ENS／ドメインの解決 — ウォレットアドレスとして vitalik.eth をそのまま渡してください
7. Foundational のみの機能 — 履歴残高、任意のブロック時点でのトークン保有者、プールのスポット価格、トレースフラグ
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	ブロックデータ、イベントログ、ガス価格、トークン価格、またはチェーンメタデータが必要な場合
integration-guide.md	全チェーン名の表、検証ルール、エラーコード、または FAQ の回答が必要な場合
workflows.md	複数ステップのワークフローを計画する場合、またはよくあるエラーをデバッグする場合