etherscan-api

Etherscan API V2

概要

Etherscan の統合 API V2 を使用して、ブロックチェーンデータを照会します。このスキルでは、以下に対応しています。

• ネイティブ ETH 残高の照会
• ERC-20 トークン残高の照会（単一のコントラクト。すべての保有資産を照会するには PRO プランが必要です）
• トランザクション履歴の照会（通常、内部、ERC-20/ERC-721/ERC-1155 の転送）
• chainid パラメーターを使用したマルチチェーン対応

対象範囲： このスキルは、無料プランのアカウント向けの読み取り専用アカウント照会に重点を置いています。Etherscan API のその他の機能については、フォールバックのドキュメントを参照してください。

前提条件

API キーの検証

API 呼び出しを行う前に、ETHERSCAN_API_KEY 環境変数が設定されていることを確認してください。

if [ -z "$ETHERSCAN_API_KEY" ]; then
  echo "Error: ETHERSCAN_API_KEY environment variable is not set."
  echo "Get a free API key at: https://etherscan.io/myapikey"
  exit 1
fi

環境変数が設定されていない場合は、ユーザーに伝えて実行を中止してください。

チェーンの推定

Ethereum Mainnet を既定値にしないでください。API 呼び出しを行う前に、必ずユーザーのプロンプトからチェーンを推定してください。

推定ルール

1. チェーンの明示的な指定 — ユーザーがチェーン名（例：「Polygon で」「Arbitrum の残高」「Base chain」）を指定した場合は、そのチェーンを使用します。
2. チェーン固有のトークン — 主に特定のチェーンに存在するトークンもあります。
   • POL → Polygon（137）
   • ARB → Arbitrum One（42161）
   • OP → OP Mainnet（10）
   • AVAX → Avalanche C-Chain（43114）
   • BNB → BNB Smart Chain（56）
   • SONIC → Sonic（146）
   • SEI → Sei（1329）
   • MON → Monad（143）
3. コントラクトアドレスのパターン — ユーザーがコントラクトアドレスを提示した場合、どのチェーンにデプロイされているか確認することを検討してください（多くのコントラクトは複数のチェーンに存在します）。
4. テストネットのキーワード — 「testnet」「Sepolia」「Hoodi」「Amoy」などの語句は、テストネットチェーンを示しています。
5. 曖昧な場合 — チェーンを推定できない場合は、続行する前にユーザーに確認してください。Ethereum Mainnet を仮定しないでください。

未対応のチェーン

ユーザーが Etherscan に対応していないチェーン（例：Solana、Bitcoin）を指定した場合は、次のように伝えてください。

The chain "[chain name]" is not supported by Etherscan API V2.

Etherscan supports EVM-compatible chains only. For the full list, see:
https://docs.etherscan.io/supported-chains

対応チェーンとその ID の完全な一覧については、./references/chains.md を参照してください。

API ベース URL

すべてのリクエストで統合 V2 エンドポイントを使用します。

https://api.etherscan.io/v2/api

chainid パラメーターによって、照会するブロックチェーンが決まります。

ETH 残高の照会

アドレスのネイティブ ETH（またはネイティブトークン）残高を照会します。

エンドポイントのパラメーター

パラメーター	必須	既定値	説明
chainid	いいえ	1	チェーン ID（chains.md を参照）
module	はい	-	account に設定
action	はい	-	balance に設定
address	はい	-	ウォレットアドレス（カンマ区切りで最大 20 件に対応）
tag	いいえ	latest	latest または 16 進数のブロック番号（直近 128 ブロックのみ。より古い履歴には balancehistory PRO エンドポイントが必要）
apikey	はい	-	$ETHERSCAN_API_KEY の API キー

単一アドレスの照会

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

複数アドレスの照会（最大 20 件）

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balancemulti&address=0xaddress1,0xaddress2,0xaddress3&tag=latest&apikey=$ETHERSCAN_API_KEY"

レスポンス形式

単一アドレス：

{
  "status": "1",
  "message": "OK",
  "result": "172774397764084972158218"
}

複数アドレス：

{
  "status": "1",
  "message": "OK",
  "result": [
    {"account": "0xaddress1", "balance": "1000000000000000000"},
    {"account": "0xaddress2", "balance": "2500000000000000000"}
  ]
}

ERC-20 トークン残高の照会

アドレスの ERC-20 トークン残高を照会します。

エンドポイントのパラメーター

パラメーター	必須	既定値	説明
chainid	いいえ	1	チェーン ID（chains.md を参照）
module	はい	-	account に設定
action	はい	-	tokenbalance に設定
contractaddress	はい	-	ERC-20 トークンのコントラクトアドレス
address	はい	-	照会するウォレットアドレス
tag	いいえ	latest	ブロックタグ
apikey	はい	-	$ETHERSCAN_API_KEY の API キー

照会例

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalance&contractaddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

レスポンス形式

{
  "status": "1",
  "message": "OK",
  "result": "135499000000"
}

全保有トークン（PRO 専用）

tokenbalance は、一度に 1 つの ERC-20 コントラクトの残高を返します。アドレスが保有する すべてのトークンを一覧表示するには、PRO エンドポイントを使用します。

Action	返される内容
addresstokenbalance	すべての ERC-20 保有トークン（トークン、数量、小数桁数、USD 価格）
addresstokennftbalance	すべての ERC-721 コレクションの保有状況と数量

どちらも Standard プラン以上が必要で、プランにかかわらず 1 秒あたり 2 回に制限されています。無料プランでは、既知のトークンコントラクトごとに tokenbalance を呼び出す方法が代替手段となります。

トランザクション履歴のクエリ

アドレスのトランザクション履歴をクエリします。module=account では、次の 5 つのアクションを使用できます。

Action	返される内容
txlist	通常の（外部）トランザクション
txlistinternal	内部トランザクション（コントラクトによって開始）
tokentx	ERC-20 トークンの転送イベント
tokennfttx	ERC-721（NFT）トークンの転送イベント
token1155tx	ERC-1155 トークンの転送イベント

エンドポイントのパラメーター

Parameter	必須	デフォルト	説明
chainid	いいえ	1	チェーン ID（chains.md を参照）
module	はい	-	account に設定
action	はい	-	上記のいずれかのアクション
address	はい	-	ウォレットアドレス
contractaddress	いいえ	-	トークンコントラクトのフィルター（tokentx／tokennfttx／token1155tx）
startblock	いいえ	0	開始ブロック番号
endblock	いいえ	999999999	終了ブロック番号
page	いいえ	1	ページネーションのページ番号
offset	いいえ	100	1 ページあたりの結果数（下記の無料プランの制限に関する注記を参照）
sort	いいえ	asc	ブロック番号順の asc または desc
apikey	はい	-	$ETHERSCAN_API_KEY から取得した API キー

2026 年 7 月 1 日から有効となる無料プランの制限変更： txlist、txlistinternal、tokentx、tokennfttx、token1155tx およびその他いくつかのリストエンドポイントで、無料プランアカウントの offset の上限が 10000 から 1000 に引き下げられます。今後も互換性を保つため、1,000 件以下の単位でページネーションしてください。有料プランでは上限 10,000 が維持されます。

クエリの例

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlist&address=0x8877bcb2223682048baDD5b09b7eE5a8FA2F3424&startblock=0&endblock=999999999&page=1&offset=100&sort=desc&apikey=$ETHERSCAN_API_KEY"

レスポンス形式

result はトランザクションオブジェクトの配列です。各オブジェクトには、Unix timeStamp（秒単位の文字列）と、チェーン固有のフィールド（hash、from、to、value、gasUsed など）が含まれます。

{
  "status": "1",
  "message": "OK",
  "result": [
    {
      "blockNumber": "18000000",
      "timeStamp": "1693526400",
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "gasUsed": "21000"
    }
  ]
}

タイムスタンプの変換

timeStamp は秒単位の Unix エポックです。必ず タイムゾーン対応の UTC 日時を生成してください。

from datetime import datetime, timezone

dt = datetime.fromtimestamp(int(tx["timeStamp"]), tz=timezone.utc)

datetime.utcfromtimestamp() は使用しないでください。naive datetime を返し、Python 3.12 以降では非推奨です。

# Shell equivalent (GNU date)
date -u -d "@1693526400" --iso-8601=seconds
# macOS / BSD date
date -u -r 1693526400 +"%Y-%m-%dT%H:%M:%SZ"

マルチチェーンでの使用

異なるブロックチェーンをクエリするには、chainid パラメーターを指定します。

よく使用されるチェーン ID（無料プラン）

チェーン	チェーン ID
Ethereum	1
Polygon	137
Arbitrum One	42161
Linea	59144
Blast	81457
Unichain	130
Mantle	5000

例：Polygon クエリ

curl -s "https://api.etherscan.io/v2/api?chainid=137&module=account&action=balance&address=0x...&tag=latest&apikey=$ETHERSCAN_API_KEY"

サポートされているチェーンの一覧については、./references/chains.md を参照してください。

Wei から人間が読みやすい形式への変換

API のレスポンスでは、残高は最小単位（ETH の場合は wei、トークンの場合は最小の小数単位）で返されます。

ETH の変換

10^18 で割ります。

# Using bc for precision
echo "scale=18; 172774397764084972158218 / 1000000000000000000" | bc
# Result: 172774.397764084972158218

ERC-20 の変換

10^decimals で割ります（通常は 18 ですが、トークンごとに異なります）。

トークン	小数桁数
ほとんどのトークン	18
USDC、USDT	6
WBTC	8

# USDC example (6 decimals)
echo "scale=6; 135499000000 / 1000000" | bc
# Result: 135499.000000

出力形式

デフォルトの動作： 結果は Markdown の表で提示します。

| Address | Balance (ETH) | Chain |
|---------|---------------|-------|
| 0xde0B...7BAe | 172,774.40 | Ethereum |
| 0xabc1...2def | 50.25 | Polygon |

ユーザーの希望： ユーザーが特定の形式（JSON、CSV、プレーンテキストなど）を指定した場合は、その形式を使用してください。ユーザーが別の出力形式を指定した場合は、Markdown の表を生成しないでください。

無料プランの制限

以下のチェーンは有料の Etherscan プランが必要で、無料プランでは利用できません。

• Base（8453）
• OP Mainnet（10）
• Avalanche C-Chain（43114）
• BNB Smart Chain（56）

ユーザーがこれらのチェーンでのクエリを依頼した場合は、有料プランが必要であることを伝えてください。

エラー処理

一般的なエラーレスポンス

ステータス	メッセージ	原因
0	NOTOK	API キーが無効、またはレート制限中
0	Invalid address format	アドレスの形式が不正
0	No transactions found	アドレスにアクティビティがない

レート制限（無料プラン）

• 1 秒あたり 3 回の呼び出し
• 1 日あたり 100,000 回の呼び出し

Lite プランでは 1 秒あたり 5 回まで増え、上位プランではさらに増えます。詳細な上限については、https://docs.etherscan.io/resources/rate-limits を参照してください。

レート制限に達した場合は、少し待ってから再試行してください。

参照ファイル

• ./references/chains.md - サポートされているチェーンとチェーン ID の完全な一覧

フォールバック用ドキュメント

このスキルで対応していないユースケース（トランザクション履歴、コントラクトの検証、ガス見積もりなど）については、AI 向けドキュメントを取得してください。

https://docs.etherscan.io/llms.txt

WebFetch を使用してこのドキュメントを取得すると、API の拡張機能を利用できます。