etherscan-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Etherscan API V2

Overview

概述

Query blockchain balances using Etherscan's unified API V2. This skill covers:

Native ETH balance queries
ERC-20 token balance queries
Multi-chain support via the
```
chainid
```
parameter

Scope: This skill focuses on balance queries for free-tier accounts. For other Etherscan API features, consult the fallback documentation.

使用Etherscan的统一API V2查询区块链余额。本Skill涵盖以下内容：

原生ETH余额查询
ERC-20代币余额查询
通过
```
chainid
```
参数实现多链支持

适用范围： 本Skill专注于免费层级账户的余额查询。如需使用Etherscan API的其他功能，请参考备用文档。

Prerequisites

前提条件

API Key Validation

API密钥验证

Before making any API call, verify the

ETHERSCAN_API_KEY

environment variable is set:

bash

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

If the environment variable is missing, inform the user and halt execution.

在发起任何API调用前，请确认已设置

ETHERSCAN_API_KEY

环境变量：

bash

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

若环境变量缺失，请告知用户并终止执行。

Chain Inference

链推断

Do not default to Ethereum Mainnet. Always infer the chain from the user's prompt before making any API call.

请勿默认使用以太坊主网。在发起任何API调用前，务必从用户的提示中推断目标链。

Inference Rules

推断规则

Explicit chain mention — If the user mentions a chain name (e.g., "on Polygon", "Arbitrum balance", "Base chain"), use that chain.
Chain-specific tokens — Some tokens exist primarily on specific chains:
- 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)
Contract address patterns — If the user provides a contract address, consider asking which chain it's deployed on (many contracts exist on multiple chains).
Testnet keywords — Words like "testnet", "Sepolia", "Holesky", "Amoy" indicate testnet chains.
Ambiguous cases — If the chain cannot be inferred, ask the user before proceeding. Do not assume Ethereum Mainnet.

明确提及链名称 —— 如果用户提到链名称（例如「在Polygon上」「Arbitrum余额」「Base链」），则使用该链。
链专属代币 —— 部分代币主要存在于特定链上：
- POL → Polygon（137）
- ARB → Arbitrum One（42161）
- OP → OP主网（10）
- AVAX → Avalanche C-Chain（43114）
- BNB → BNB智能链（56）
- SONIC → Sonic（146）
- SEI → Sei（1329）
- MON → Monad（143）
合约地址模式 —— 如果用户提供合约地址，请询问该合约部署在哪个链上（许多合约会部署在多条链上）。
测试网关键词 —— 出现「testnet」「Sepolia」「Holesky」「Amoy」等词汇时，表明是测试网链。
模糊场景 —— 如果无法推断链信息，请先询问用户，不要默认使用以太坊主网。

Unsupported Chains

不支持的链

If the user references a chain not supported by Etherscan (e.g., Solana, Bitcoin), inform them:

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/etherscan-v2/getting-started/supported-chains

For the complete list of supported chains and their IDs, see

./references/CHAINS.md

如果用户提及Etherscan不支持的链（例如Solana、Bitcoin），请告知用户：

该链「[链名称]」不受Etherscan API V2支持。

Etherscan仅支持兼容EVM的链。完整支持列表请查看：
https://docs.etherscan.io/etherscan-v2/getting-started/supported-chains

如需获取完整的支持链及其ID列表，请查看

./references/CHAINS.md

。

API Base URL

API基础URL

All requests use the unified V2 endpoint:

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

The

chainid

parameter determines which blockchain to query.

所有请求均使用统一的V2端点：

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

chainid

参数决定要查询的区块链。

ETH Balance Query

ETH余额查询

Query native ETH (or native token) balance for an address.

查询地址的原生ETH（或其他原生代币）余额。

Endpoint Parameters

端点参数

Parameter	Required	Default	Description
`chainid`	No	`1`	Chain ID (see CHAINS.md)
`module`	Yes	-	Set to `account`
`action`	Yes	-	Set to `balance`
`address`	Yes	-	Wallet address (supports up to 20 comma-separated)
`tag`	No	`latest`	Block tag ( `latest` , `pending` , or hex block number)
`apikey`	Yes	-	API key from `$ETHERSCAN_API_KEY`

参数	是否必填	默认值	描述
`chainid`	否	`1`	链ID（查看CHAINS.md）
`module`	是	-	设置为 `account`
`action`	是	-	设置为 `balance`
`address`	是	-	钱包地址（最多支持20个地址用逗号分隔）
`tag`	否	`latest`	区块标签（ `latest` 、 `pending` 或十六进制区块号）
`apikey`	是	-	来自 `$ETHERSCAN_API_KEY` 的API密钥

Single Address Query

单地址查询

bash

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

bash

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

Multi-Address Query (up to 20)

多地址查询（最多20个）

bash

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

bash

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

Response Format

响应格式

Single address:

json

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

Multi-address:

json

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

单地址：

json

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

多地址：

json

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

ERC-20 Token Balance Query

ERC-20代币余额查询

Query ERC-20 token balance for an address.

查询地址的ERC-20代币余额。

Endpoint Parameters

端点参数

Parameter	Required	Default	Description
`chainid`	No	`1`	Chain ID (see CHAINS.md)
`module`	Yes	-	Set to `account`
`action`	Yes	-	Set to `tokenbalance`
`contractaddress`	Yes	-	ERC-20 token contract address
`address`	Yes	-	Wallet address to query
`tag`	No	`latest`	Block tag
`apikey`	Yes	-	API key from `$ETHERSCAN_API_KEY`

参数	是否必填	默认值	描述
`chainid`	否	`1`	链ID（查看CHAINS.md）
`module`	是	-	设置为 `account`
`action`	是	-	设置为 `tokenbalance`
`contractaddress`	是	-	ERC-20代币合约地址
`address`	是	-	要查询的钱包地址
`tag`	否	`latest`	区块标签
`apikey`	是	-	来自 `$ETHERSCAN_API_KEY` 的API密钥

Example Query

查询示例

bash

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

bash

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

Response Format

响应格式

json

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

json

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

Multi-Chain Usage

多链使用

Specify the

chainid

parameter to query different blockchains.

指定

chainid

参数即可查询不同区块链。

Common Chain IDs (Free Tier)

常见链ID（免费层级）

Chain	Chain ID
Ethereum	`1`
Polygon	`137`
Arbitrum One	`42161`
Linea	`59144`
Scroll	`534352`
zkSync	`324`

链	链ID
Ethereum	`1`
Polygon	`137`
Arbitrum One	`42161`
Linea	`59144`
Scroll	`534352`
zkSync	`324`

Example: Polygon Query

示例：Polygon查询

bash

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

For the complete list of supported chains, see

./references/CHAINS.md

bash

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 to Human-Readable Conversion

Wei转易读格式

API responses return balances in the smallest unit (wei for ETH, smallest decimals for tokens).

API响应返回的余额为最小单位（ETH为wei，代币为对应最小小数单位）。

ETH Conversion

ETH转换

Divide by 10^18:

bash

undefined

除以10^18：

bash

undefined

Using bc for precision

使用bc保证精度

echo "scale=18; 172774397764084972158218 / 1000000000000000000" | bc

Result: 172774.397764084972158218

结果：172774.397764084972158218

undefined

undefined

ERC-20 Conversion

ERC-20转换

Divide by 10^decimals (typically 18, but varies per token):

Token	Decimals
Most tokens	18
USDC, USDT	6
WBTC	8

bash

undefined

除以10^小数位数（通常为18，但不同代币可能不同）：

代币	小数位数
大多数代币	18
USDC、USDT	6
WBTC	8

bash

undefined

USDC example (6 decimals)

USDC示例（6位小数）

echo "scale=6; 135499000000 / 1000000" | bc

Result: 135499.000000

结果：135499.000000

undefined

undefined

Output Formatting

输出格式

Default behavior: Present results in a Markdown table:

markdown

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

User preference: If the user requests a specific format (JSON, CSV, plain text, etc.), use that format instead. Do not generate a Markdown table when the user specifies an alternative output format.

默认行为： 以Markdown表格形式展示结果：

markdown

| 地址 | 余额（ETH） | 链 |
|---------|---------------|-------|
| 0xde0B...7BAe | 172,774.40 | Ethereum |
| 0xabc1...2def | 50.25 | Polygon |

用户偏好： 如果用户要求特定格式（JSON、CSV、纯文本等），则使用该格式。当用户指定其他输出格式时，不要生成Markdown表格。

Free Tier Limitations

免费层级限制

The following chains require a paid Etherscan plan and are not available on free tier:

Base (
```
8453
```
)
OP Mainnet (
```
10
```
)
Avalanche C-Chain (
```
43114
```
)
BNB Smart Chain (
```
56
```
)

If a user requests a query on these chains, inform them that a paid plan is required.

以下链需要Etherscan付费套餐，免费层级不支持：

Base (
```
8453
```
)
OP主网 (
```
10
```
)
Avalanche C-Chain (
```
43114
```
)
BNB智能链 (
```
56
```
)

如果用户请求查询这些链，请告知他们需要付费套餐。

Error Handling

错误处理

Common Error Responses

常见错误响应

Status	Message	Cause
`0`	`NOTOK`	Invalid API key or rate limited
`0`	`Invalid address format`	Malformed address
`0`	`No transactions found`	Address has no activity

状态码	消息	原因
`0`	`NOTOK`	API密钥无效或触发速率限制
`0`	`Invalid address format`	地址格式错误
`0`	`No transactions found`	地址无任何活动记录

Rate Limits (Free Tier)

速率限制（免费层级）

5 calls/second
100,000 calls/day

If rate limited, wait briefly and retry.

5次调用/秒
100,000次调用/天

如果触发速率限制，请稍作等待后重试。

Reference Files

参考文件

./references/CHAINS.md
- Complete list of supported chains with chain IDs

./references/CHAINS.md
- 完整的支持链列表及对应链ID

Fallback Documentation

备用文档

For use cases not covered by this skill (transaction history, contract verification, gas estimates, etc.), fetch the AI-friendly documentation:

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

Use

WebFetch

to retrieve this documentation for extended API capabilities.

对于本Skill未覆盖的使用场景（交易历史、合约验证、gas估算等），请获取AI友好型文档：

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

使用

WebFetch

获取该文档以扩展API功能。