Get TRC20 Token Transfer List for an Address

1. Overview & Typical Use

Query TRC20 token transfer records for a specified address, with support for filtering by direction (in / out), time range, and other conditions.

Typical use: wallet TRC20 token transaction history display, querying inbound/outbound transfer details for a specific token.
When not to use: for TRX transfers use “Get TRX Transfer List for an Address”; for TRC10 token transfers use “Get TRC10 Token Transfer List for an Address”.

GET /api/transfer/trc20

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

Parameter	Type	Required	Default	Description
`address`	string	Yes	—	Query address
`trc20Id`	string	Yes	—	TRC20 token contract address
`start`	integer	No	`0`	Start offset; `start + limit ≤ 10000`
`limit`	integer	No	`20`	Page size, max 50
`direction`	integer	No	`1`	Transfer direction: `1` out (address is sender), `2` in (address is recipient), `0` all
`start_timestamp`	integer	No	`1529769600000`	Start time, ms timestamp
`end_timestamp`	integer	No	—	End time, ms timestamp
`db_version`	integer	No	`0`	Filter invalid transfers
`reverse`	boolean	No	`true`	Sort data in descending order

Top-level

Field	Type	Required	Description	Unit/Precision
`code`	integer	Required	Status code	—
`page_size`	integer	Required	Number of records returned on the current page	—
`tokenInfo`	object	Required	TRC20 token metadata; see schema below	—
`data`	array	Required	Transfer record array; see below	—
`contractMap`	object	Optional	Address → whether it is a contract mapping	—

data[] elements

Field	Type	Required	Description	Unit/Precision
`hash`	string	Required	Transaction hash	—
`block`	integer	Required	Block height	—
`block_timestamp`	integer	Required	Block time	ms timestamp
`from`	string	Required	Sender address	—
`to`	string	Required	Recipient address	—
`amount`	string	Required	Transfer quantity (raw value); fixed to `"0"` for Approval events	Must be converted using `decimals`
`status`	integer	Optional	Transaction status code; present only for Transfer events	—
`approval_amount`	string	Required	Approval quantity; fixed to `"0"` for Transfer events	—
`approval_amount_unlimited`	string	Optional	Present only when approval amount exceeds 10^(18+decimals); value is fixed to `"unlimited"`	—
`event_type`	string	Required	Event type (“Transfer” / “Approval”); set to empty string when from is a contract address and type is Transfer	—
`confirmed`	integer	Required	Whether confirmed; defaults to 1	—
`contract_type`	string	Required	Contract type; fixed to `"TriggerSmartContract"`	—
`contractType`	integer	Required	Contract type number; fixed to `31`	—
`revert`	integer	Required	Whether reverted; 1 means reverted	—
`contract_ret`	string	Required	Contract execution result; defaults to “SUCCESS”	—
`direction`	integer	Required	Transfer direction: 1 = address is sender (out), 2 = address is recipient (in)	—
`decimals`	integer	Required	Token decimals	—
`token_name`	string	Required	Token contract name	—
`id`	string	Required	Token contract address (= request parameter `trc20Id`)	—
`issue_address`	string	Required	Token issuer address	—

tokenInfo object schema (9 common fields):

Field	Type	Required	Description	Unit/Precision
`tokenId`	string	Required	Token contract address (Base58); TRX placeholder is `_`	—
`tokenAbbr`	string	Required	Token abbreviation (e.g. `USDT` / `TRX`)	—
`tokenName`	string	Required	Token name	—
`tokenDecimal`	integer	Required	Decimal precision (required to convert the `amount` field)	—
`tokenCanShow`	integer	Required	Whether displayable (`1` yes / `0` no)	—
`tokenType`	string	Required	Token type (`trc10` / `trc20` / `trc721` / `trc1155`)	—
`tokenLogo`	string	Required	Token logo URL	—
`tokenLevel`	string	Required	Token level	—
`vip`	boolean	Required	Whether it is a VIP token	—

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

Required parameters: both address and trc20Id are required; missing either returns an error.
Parameter violations are not reported as errors: limit > 50, start + limit > 10000, etc. are silently truncated.
Empty result is not an error: no matches returns 200 + data: [], which is a normal response.