对于区块链开发者和数据分析师来说，高效获取链上 Token 信息至关重要。无论是查询代币总供应量、地址余额，还是分析持仓分布，API 接口都是实现自动化数据获取的核心工具。本文将系统介绍以太坊 Token 相关信息查询的主要 API 接口及其应用场景。
核心 Token 数据查询接口
获取 ERC-20 代币总供应量
通过指定代币合约地址，您可以快速获取该代币的当前流通总量。此接口适用于代币经济模型分析、市值计算等场景。
请求示例：
https://api.etherscan.io/api
?module=stats
&action=tokensupply
&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
&apikey=YourApiKeyToken查询参数说明：
contractaddress：ERC-20 代币的合约地址
查询地址的 ERC-20 代币余额
此接口返回指定地址持有的特定 ERC-20 代币数量，是构建钱包应用或持仓监控系统的基础。
请求示例：
https://api.etherscan.io/api
?module=account
&action=tokenbalance
&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
&address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
&tag=latest&apikey=YourApiKeyToken查询参数说明：
contractaddress：ERC-20 代币合约地址address：要查询余额的目标地址
历史数据查询接口
获取历史 ERC-20 代币总供应量
此接口可查询特定区块高度时的代币流通总量，对于回溯性分析和研究代币发行历史非常有价值。
注意：此接口限流为每秒 2 次调用，不受 API Pro 套餐等级影响。
请求示例：
https://api.etherscan.io/api
?module=stats
&action=tokensupplyhistory
&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
&blockno=8000000
&apikey=YourApiKeyToken查询参数说明：
contractaddress：ERC-20 代币合约地址blockno：要查询的区块号（整数）
查询地址的历史 ERC-20 代币余额
通过指定区块号，可以获取过去某一时刻地址的代币持仓情况，适用于交易审计和历史状态验证。
注意：此接口同样限流为每秒 2 次调用。
请求示例：
https://api.etherscan.io/api
?module=account
&action=tokenbalancehistory
&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
&address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
&blockno=8000000
&apikey=YourApiKeyToken查询参数说明：
contractaddress：ERC-20 代币合约地址address：要查询余额的目标地址blockno：要查询的区块号
持币地址分析接口
获取代币持币地址列表
此接口返回当前持有特定 ERC-20 代币的所有地址及其持仓数量，支持分页查询。
请求示例：
https://api.etherscan.io/api
?module=token
&action=tokenholderlist
&contractaddress=0xaaaebe6fe48e54f431b0c390cfaf0b017d09d42d
&page=1
&offset=10
&apikey=YourApiKeyToken查询参数说明：
contractaddress：ERC-20 代币合约地址page：页码（启用分页时）offset：每页显示的记录数
获取代币持币地址数量
快速查询持有特定 ERC-20 代币的地址总数，适用于代币分布集中度分析。
请求示例：
https://api.etherscan.io/api
?module=token
&action=tokenholdercount
&contractaddress=0xaaaebe6fe48e54f431b0c390cfaf0b017d09d42d
&apikey=YourApiKeyToken查询参数说明：
contractaddress：ERC-20 代币合约地址
Token 信息查询接口
获取代币基本信息
返回 ERC20/ERC721/ERC1155 代币的项目信息和社交媒体链接，包括代币名称、符号、小数位数等元数据。
注意：此接口限流为每秒 2 次调用。
请求示例：
https://api.etherscan.io/api
?module=token
&action=tokeninfo
&contractaddress=0x0e3a2a1f2146d86a604adc220b4967a898d7fe07
&apikey=YourApiKeyToken查询参数说明：
contractaddress：要检索信息的 ERC-20/ERC-721 代币合约地址
地址 Token 持仓查询
查询地址持有的 ERC-20 代币
返回指定地址持有的所有 ERC-20 代币及其数量，是构建资产看板的核心接口。
注意：此接口限流为每秒 2 次调用。
请求示例：
https://api.etherscan.io/api
?module=account
&action=addresstokenbalance
&address=0x983e3660c0bE01991785F80f266A84B911ab59b0
&page=1
&offset=100
&apikey=YourApiKeyToken查询参数说明：
address：要查询余额的目标地址page：页码（启用分页时）offset：每页显示的记录数
查询地址持有的 ERC-721 代币（NFT）
返回指定地址持有的所有 ERC-721 代币（NFT）及其数量，适用于 NFT 资产管理系统。
注意：此接口限流为每秒 2 次调用。
请求示例：
https://api.etherscan.io/api
?module=account
&action=addresstokennftbalance
&address=0x6b52e83941eb10f9c613c395a834457559a80114
&page=1
&offset=100
&apikey=YourApiKeyToken查询参数说明：
address：要查询余额的目标地址page：页码（启用分页时）offset：每页显示的记录数
按合约地址查询地址的 ERC-721 代币库存
返回指定地址在特定 ERC-721 合约下持有的代币清单，支持精确过滤。
注意：此接口限流为每秒 2 次调用，每查询限制显示 1000 条记录，可使用 page 参数获取后续记录。
请求示例：
https://api.etherscan.io/api
?module=account
&action=addresstokennftinventory
&address=0x123432244443b54409430979df8333f9308a6040
&contractaddress=0xed5af388653567af2f388e6224dc7c4b3241c544
&page=1
&offset=100
&apikey=YourApiKeyToken查询参数说明：
address：要查询库存的目标地址contractaddress：要查询的 ERC-721 代币合约地址page：页码（启用分页时）offset：每页显示的记录数
常见问题
这些 API 接口是否需要付费？
部分高级接口需要 API Pro 订阅。基础接口通常有免费调用额度，但对于高频或商业用途，建议升级 API 计划以获得更好的服务质量和调用频次。
如何提高 API 调用频率限制？
👉 获取专业级 API 访问权限可以显著提升调用限制，满足企业级应用需求。专业套餐通常提供更高的每秒调用次数和更稳定的服务质量。
查询历史余额数据有什么实际应用场景？
历史余额数据在审计、税务计算、投资分析等领域非常重要。它可以用于证明某个时间点的资产状况，或者分析投资策略的历史表现。
ERC-20 和 ERC-721 代币查询接口有什么区别？
ERC-20 是同质化代币标准，接口返回的是数量；而 ERC-721 是非同质化代币（NFT），接口返回的是具体的代币 ID 和元数据信息。
分页参数应该如何设置才能优化查询效率？
建议根据实际需求设置合适的 offset 值：对于大量数据查询，设置较大的 offset 可以减少请求次数；对于实时显示，较小的 offset 可以提高响应速度。同时合理使用 page 参数来遍历所有结果。
API 返回错误代码时如何排查？
常见错误包括无效的合约地址、不支持的模块操作或超过调用限制。请检查参数格式是否正确，并确认您的 API 密钥是否有权限访问目标接口。