Get TRC20/TRC721/TRC1155 Token Holders

1. Overview & Typical Use

Returns the holder list for TRC20/TRC721/TRC1155 tokens, sorted by holding amount in descending order.

Typical use: token holder rankings, whale position analysis, address-specific holding query.
When not to use: for TRC10 token holders use “Get TRC10 Token Holders”; for holding distribution use “Get Holder Token Position Distribution”.

GET /api/token_trc20/holders

For Base URL and authentication, see Common Network & Authentication.

Parameter	Type	Required	Default	Description
`contract_address`	string	No	—	Contract address; at least one of `contract_address` or `holder_address` is required
`holder_address`	string	No	—	Holder address; at least one of `contract_address` or `holder_address` is required
`start`	integer	No	`0`	Start index; `start + limit ≤ 10000`
`limit`	integer	No	`10`	Items per page, max 50

Top-level

Field	Type	Required	Description	Unit/Precision
`total`	integer	Required	Number of hits (cap 10000)	—
`rangeTotal`	integer	Required	True total number of holders	—
`contractMap`	object	Required	Address → whether the address is a contract (includes holder addresses)	—
`contractInfo`	object	Required	Contract address → tag info (value schema below)	—
`trc20_tokens`	array	Required	Holder list; see below	—

contractInfo[<addr>] object schema (8 fields):

Field	Type	Required	Description
`tag1`	string	Required	Primary label (project name / contract name / exchange name)
`tag1Url`	string	Required	URL of the primary label (may be an empty string)
`name`	string	Required	Formal contract / project name
`isToken`	boolean	Required	Whether it is a token contract (`true` / `false`)
`vip`	boolean	Required	Whether it is a VIP entity (`true` / `false`)
`risk`	boolean \| string	Required	Risk label; most endpoints return boolean, some return a string risk type (`blacklist` / `fraud`, etc.)
`publicTagDesc`	string	Required	Public label description; empty string for most accounts
`publicTag`	string	Optional	Public label (e.g. `"USDT Token"` / `"Binance"`); returned only for well-known entities or certain endpoints

trc20_tokens[] elements

Field	Type	Required	Description	Unit/Precision
`holder_address`	string	Required	Holder address	—
`balance`	string	Required	Holding balance (raw string; requires `decimals` to convert)	—
`updateTime`	integer	Required	Last update time	Millisecond timestamp
`updateBlock`	integer	Required	Last update block height	—
`addressTag`	string	Required	Address tag (empty string when no tag)	—
`addressTagLogo`	string	Required	Address tag logo URL (empty string when no tag)	—
`publicTagDesc`	string	Required	Public tag description (may be empty string)	—
`srTag`	boolean	Required	Whether this is a Super Representative	—
`srName`	string	Required	SR name (empty string when not an SR)	—
`foundationTag`	boolean	Required	Whether this is a Foundation address	—
`analysisShow`	boolean	Required	Whether to show in analytics	—

For HTTP status codes, see Common Errors. Key points for this endpoint: