获取 TRC10 代币持有者
1. 概述与典型用途
返回 TRC10 代币的持有者列表，默认按持有量降序排列。
- 典型用途：TRC10 代币持有者排行、大户分析。
- 何时不要用：查询 TRC20/TRC721/TRC1155 代币持有者用「获取 TRC20/TRC721/TRC1155 代币持有者」。
2. 接口与鉴权
GET /api/tokenholders
Base URL 与鉴权见 公共网络与鉴权说明。
3. 请求
字段
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
address | string | 是 | — | TRC10 发行方地址或代币 ID；_ 表示 TRX |
holder_address | string | 否 | — | TRC10 持有者地址 |
start | integer | 否 | 0 | 起始编号；start + limit ≤ 10000 |
limit | integer | 否 | 10 | 每页数量，最大 50 |
sort | string | 否 | -balance | 排序：-balance 降序，balance 升序 |
4. 响应
字段
顶层
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
total | integer | 必返 | 命中总数（上限 10000） | — |
rangeTotal | integer | 必返 | 真实持有者总数 | — |
contractMap | object | 必返 | 地址 → 是否为合约的映射 | — |
contractInfo | object | 可选 | 合约地址 → 标签信息（涉及合约地址时有） | — |
account_number | integer | 可选 | 账户总数（仅 TRX 即 address=_ 时有） | — |
last_24h_account_change | integer | 可选 | 24 小时账户数变化（仅 TRX 时有） | — |
data | array | 必返 | 持有者列表，普通 TRC10 与 TRX 的字段分别见下 | — |
data[] 元素（普通 TRC10 代币）
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
address | string | 必返 | 持有者地址 | — |
name | string | 必返 | 持有者记录名称 | — |
balance | string | 必返 | 最小单位持有量；代币数量 = balance / 10^precision，precision 取自该资产的 TRC10 代币元数据 | 资产最小单位 |
balanceInUsd | string | 可选 | 持有量的美元价值 | USD |
updateTime | integer | 必返 | 最后更新时间 | 毫秒时间戳 ms |
index | integer | 必返 | 排列序号 | — |
srTag | boolean | 可选 | 是否为超级代表 | — |
foundationTag | boolean | 可选 | 是否为基金会地址 | — |
srName | string | 可选 | 超级代表名称（可为空） | — |
addressTag | string | 可选 | 地址标签 | — |
addressTagLogo | string | 可选 | 地址标签 Logo URL（可为空） | — |
analysisShow | boolean | 可选 | 是否在分析中显示 | — |
data[] 元素（TRX 即 address=_ 时）
| 字段 | 类型 | 是否必返 | 说明 | 单位/精度 |
|---|---|---|---|---|
address | string | 必返 | 持有者地址 | — |
balance | integer | 必返 | 可用 TRX 余额 | SUN |
totalBalance | integer | 必返 | TRX 总余额：balance + power + unstakingBalance | SUN |
unstakingBalance | integer | 必返 | 解质押中的 TRX 金额 | SUN |
power | integer | 必返 | 质押 TRX 金额；原值不能直接当作票数，投票权需按协议规则及质押状态另行确定 | SUN |
balanceInUsd | string | 可选 | totalBalance 的美元价值 | USD |
trxRatio | string | 必返 | 占全网 TRX 比例（字符串高精度） | 小数 |
index | integer | 必返 | 排列序号 | — |
updateTime | integer | 必返 | 最后更新时间 | 毫秒时间戳 ms |
latestOperationTime | integer | 必返 | 最近操作时间 | 毫秒时间戳 ms |
srTag | boolean | 必返 | 是否为超级代表 | — |
srName | string | 必返 | 超级代表名称（非 SR 时为空字符串） | — |
foundationTag | boolean | 必返 | 是否为基金会地址 | — |
addressTagLogo | string | 必返 | 地址标签 Logo URL（可为空字符串） | — |
analysisShow | boolean | 必返 | 是否在分析中显示 | — |
5. 错误
HTTP 状态码见 公共错误说明。本接口要点：
address为必填参数：不传时返回空数据。start + limit上限为 10000。- 空结果 ≠ 错误：无命中返回
200+data: []。