https://7rikazhexde-techlog.hatenablog.com/entry/2025/10/18/233854

概要

Arbitrum Oneネットワーク上のETHやトークン残高を取得したいと思い調査しました。
従来はEthereumメインネット（L1）でv1 APIを利用できましたが、現在はv2が公開されており、v1は非推奨となっています。
また、Arbitrum Oneの残高取得はv2 APIで可能であり、v1エンドポイントでは取得できませんでした。
この記事では、v1との違いとv2による取得方法を、実際のcurlコマンド例を交えて紹介します。

前提

ネットワーク: Arbitrum One (chainid=42161)
API: Etherscan Multichain API v2
対象:
- ネイティブトークン残高（ETH/ARB）
- ERC-20 トークン残高（例: AUSDC）
前提: Etherscan APIキーを取得済み（V2およびArbitrumでも共通）

API バージョンの違い

V1 API

旧形式のエンドポイント
https://api.etherscan.io/api
Ethereum メインネット専用（L2には非対応）
module=account と action=balance / action=tokenbalance で残高取得
tag=latest パラメータを使用

例：Arbitrum One トークン残高取得

curl "https://api.arbiscan.io/api?module=account&action=tokenbalance&contractaddress=<ERC-20コントラクトアドレス>&address=<ウォレットアドレス>&tag=latest&apikey=YOUR_API_KEY"

レスポンス例（V1では非対応）

{
  "status":"0",
  "message":"NOTOK",
  "result":"You are using a deprecated V1 endpoint, switch to Etherscan API V2 using https://docs.etherscan.io/v2-migration"
}

→ Arbitrum One など L2 のデータは取得不可。

V2 API

新形式: https://api.etherscan.io/v2/api
マルチチェーン対応（chainid 指定でL2対応）
tag=latest 不要
APIキーはV1と共通利用可能
一貫したJSON形式のレスポンス
Arbitrum One（chainid=42161）を含む50以上のチェーンに対応

例1：ETH（ネイティブ残高）

curl "https://api.etherscan.io/v2/api?chainid=42161&module=account&action=balance&address=<ウォレットアドレス>&apikey=${ETHSCAN_API_KEY}" | jq

レスポンス例

{
  "status": "1",
  "message": "OK",
  "result": "<balance_in_wei>"
}

Wei → ETH換算

echo "scale=8; <balance_in_wei> / 10^18" | bc

例2：AUSDC（トークン残高）

curl "https://api.etherscan.io/v2/api?chainid=42161&module=account&action=tokenbalance&contractaddress=<AUSDCコントラクトアドレス>&address=<ウォレットアドレス>&apikey=${ETHSCAN_API_KEY}" | jq

レスポンス例

{
  "status": "1",
  "message": "OK",
  "result": "<token_balance_raw>"
}

AUSDCトークンの最小単位（6桁） → トークン換算

echo "scale=6; <token_balance_raw> / 10^6" | bc

V1 → V2 移行ガイダンス

手順	対応内容
1	ベースURLを `https://api.etherscan.io/v2/api` に変更
2	L2対応の場合は `chainid` を追加
3	`tag=latest` を削除
4	ERC-20 残高取得には `module=account&action=tokenbalance` を利用
5	APIキーは共通利用可能（再発行不要）

詳細は公式ドキュメントも確認ください。

docs.etherscan.io

レスポンス仕様まとめ

action	対象	必須パラメータ	単位	備考
`balance`	ネイティブ通貨	`address`	Wei → ETH換算	ETH, ARB など
`tokenbalance`	ERC-20トークン	`address`, `contractaddress`	最小単位 → トークン換算	USDC, AUSDC など

※ ERC-721（NFT）は別エンドポイント tokennfttx を使用。

注意点

V1 APIはすでに非推奨（deprecated）
V2では tag=latest が不要
chainid の指定忘れで L2 が取得できない
tokenbalance が一部チェーンで非対応の場合あり
Exception や "status": "0" エラーが返る場合は以下を確認
- chainid未指定
- contractaddressの誤り
- APIキーのRate Limit超過

参考ドキュメント

まとめ

Etherscan API v2では、Arbitrum Oneを含む複数チェーンの残高取得が可能である。
V1はすでに非推奨となっており、L2チェーンでは利用できませんでしたが、V2でchainid パラメータを指定することで、ETHやトークンの残高を取得できます。
ETHの場合はWei単位（10^18換算）、トークンの場合はコントラクトの decimals に基づき単位換算が必要です。

以上です。