Get TRC20 & TRC721 Transfer List

1. Overview & Typical Use

Queries TRC20 and TRC721 transfer records by contract, address, time, and other conditions, with pagination support.

Typical use: token transaction history, address inflow/outflow details, transfer monitoring for a specific contract.
When not to use: for TRX/TRC10 transfers use “Get TRX & TRC10 Transfer List”; for a single transaction use “Get Transaction Details”.

2. Endpoint & Authentication

GET /api/token_trc20/transfers

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

3. Request

Fields

Parameter	Type	Required	Default	Description
`start`	integer	No	`0`	Start index (offset); `start + limit ≤ 10000`, violations silently handled
`limit`	integer	No	`10`	Items per page, max 50 (excess silently truncated)
`contract_address`	string	No	—	Token contract address (TRC20 / TRC721)
`relatedAddress`	string	No	—	Related account address (matches either sender or receiver)
`fromAddress`	string	No	—	Sender address
`toAddress`	string	No	—	Receiver address
`start_timestamp`	integer	No	—	Start time, ms timestamp
`end_timestamp`	integer	No	—	End time, ms timestamp
`block`	integer	No	—	Filter by block number
`direction`	string	No	`all`	Transfer direction: `in` (incoming), `out` (outgoing), `all` (both)
`confirm`	string	No	—	Confirmation status: `0` confirmed / `1` unconfirmed / `2` reverted / empty all

4. Response

Fields

Top-level

Field	Type	Required	Description	Unit/Precision
`total`	integer	Required	Number of hits (cap 10000, for pagination)	—
`rangeTotal`	integer	Required	Total count within the filtered range	—
`token_transfers`	array	Required	Transfer record array; see below	—
`contractInfo`	object	Optional	Contract address → label information mapping; populated only when contract is hit (value schema below)	—
`normalAddressInfo`	object	Optional	Non-contract address → risk information mapping; each address value observed to contain only `risk` (boolean), no other sub-fields	—

token_transfers[] elements

Field	Type	Required	Description	Unit/Precision
`transaction_id`	string	Required	Transaction hash	—
`status`	integer	Required	Transaction status code	—
`block_ts`	integer	Required	Block time	ms timestamp
`block`	integer	Required	Block height	—
`from_address`	string	Required	Sender address (Base58, starts with T)	—
`to_address`	string	Required	Receiver address (Base58, starts with T)	—
`contract_address`	string	Required	Token contract address	—
`quant`	string	Required	Transfer quantity (raw string, preserves big-number precision; may exceed 2^53)	Use `tokenInfo.tokenDecimal` to convert
`approval_amount`	string	Required	Approval amount (non-Approval events return `"0"`)	—
`event_type`	string	Required	Event type: `Transfer` or `Approval`	—
`confirmed`	boolean	Required	Whether confirmed	—
`contractRet`	string	Required	Contract execution result (e.g. `SUCCESS`)	—
`finalResult`	string	Required	Final result: `SUCCESS` or `FAIL`	—
`contract_type`	string	Required	Token type: `trc20` or `trc721`	—
`tokenType2`	string	Optional	Additional token type identifier	—
`tokenInfo`	object	Required	Token metadata (value schema below)	—
`from_address_tag`	object	Required	Sender address tag info; sub-fields see the `from_address_tag` object table below	—
`fromAddressIsContract`	boolean	Required	Whether the sender is a contract address	—
`to_address_tag`	object	Required	Receiver address tag info; sub-fields see the `to_address_tag` object table below	—
`toAddressIsContract`	boolean	Required	Whether the receiver is a contract address	—
`trigger_info`	object	Optional	Contract call method and parameters; sub-fields see the `trigger_info` object table below	—
`revert`	boolean	Required	Whether reverted	—
`riskTransaction`	boolean	Required	Risk transaction flag	—

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

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	—

quant is a raw string; display value = quant / 10^tokenInfo.tokenDecimal. Example: USDT (decimals=6) quant="239215838235000" → 239,215,838.235 USDT.

from_address_tag object

Field	Type	Required	Description
`from_address_tag`	string	Required	Sender public tag text (empty string when no tag)
`from_address_tag_logo`	string	Required	Sender tag logo URL (empty string when no logo)

to_address_tag object

Field	Type	Required	Description
`to_address_tag`	string	Required	Receiver public tag text (empty string when no tag)
`to_address_tag_logo`	string	Required	Receiver tag logo URL (empty string when no logo)

trigger_info object (for contract calls)

Field	Type	Required	Description	Unit/Precision
`method`	string	Required	Method signature (e.g. `transfer(address _to,uint256 _value)`)	—
`methodName`	string	Required	Method name (e.g. `transfer`)	—
`parameter`	object	Required	Parameter object; keys are parameter names (e.g. `_to`, `_value`), values are strings	—
`data`	string	Required	Raw call data	hex
`contract_address`	string	Required	Called contract address	—
`call_value`	integer	Required	TRX amount sent with the call	sun

Example


{
  "total": 10000,
  "rangeTotal": 10000,
  "token_transfers": [
    {
      "transaction_id": "2a3312a8ecf09de3e04d1bfff461f391e2e8859d14ddb392298d71d2dc02b66e",
      "status": 0,
      "block_ts": 1778493798000,
      "from_address": "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf",
      "to_address": "TWd4WrZ9wn84f5x1hZhL4DHvk738ns5jwb",
      "block": 82608490,
      "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "quant": "239215838235000",
      "approval_amount": "0",
      "event_type": "Transfer",
      "confirmed": true,
      "contractRet": "SUCCESS",
      "finalResult": "SUCCESS",
      "tokenType2": "trc20",
      "tokenInfo": {
        "tokenId": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "tokenAbbr": "USDT",
        "tokenName": "Tether USD",
        "tokenDecimal": 6,
        "tokenCanShow": 1,
        "tokenType": "trc20",
        "tokenLogo": "https://static.tronscan.org/production/logo/usdtlogo.png",
        "tokenLevel": "2",
        "issuerAddr": "THPvaUhoh2Qn2y9THCZML3H815hhFhn5YC",
        "vip": true
      },
      "fromAddressIsContract": false,
      "from_address_tag": {
        "from_address_tag": "Binance-Hot 7",
        "from_address_tag_logo": ""
      },
      "toAddressIsContract": false,
      "to_address_tag": {
        "to_address_tag_logo": "https://coin.top/production/upload/logo/Binance.png",
        "to_address_tag": "Binance-Cold 2"
      },
      "trigger_info": {
        "method": "transfer(address _to,uint256 _value)",
        "data": "a9059cbb000000000000000000000041e28b3cfd4e0e909077821478e9fcb86b84be786e0000000000000000000000000000000000000000000000000000d990c7100978",
        "parameter": {
          "_value": "239215838235000",
          "_to": "TWd4WrZ9wn84f5x1hZhL4DHvk738ns5jwb"
        },
        "methodName": "transfer",
        "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "call_value": 0
      },
      "revert": false,
      "contract_type": "trc20",
      "riskTransaction": false
    }
  ],
  "contractInfo": {},
  "normalAddressInfo": {
    "TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf": {
      "risk": false
    },
    "TWd4WrZ9wn84f5x1hZhL4DHvk738ns5jwb": {
      "risk": false
    }
  }
}

Interpretation: quant="239215838235000", tokenDecimal=6 → 239,215,838.235 USDT.

5. Errors

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

Invalid parameters do not cause errors: limit > 50, start + limit > 10000, etc. are silently truncated/capped and return 200 — do not rely on errors to detect parameter issues.
Empty result is not an error: no matches returns 200 + token_transfers: [] — this is a normal response.