Get Internal Transaction List

1. Overview & Typical Use

Queries smart contract internal transaction records by address / contract / block and other criteria, with pagination support.

Typical use: tracing contract internal call chains, viewing internal TRX transfers, monitoring contract-to-contract interactions.
When not to use: to query regular transactions, use “Get Transaction List”; to query token transfers, use the corresponding transfer list endpoint.

GET /api/internal-transaction

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

Parameter	Type	Required	Default	Description
`start`	integer	No	`0`	Start index (offset); `start + limit ≤ 10000`, excess is silently handled
`limit`	integer	No	`10`	Page size, maximum 50 (excess is silently truncated)
`address`	string	No	—	Specify address; at least one of `address`, `block`, `contract` is required
`contract`	string	No	—	Filter by contract address
`block`	integer	No	—	Filter by block number
`start_timestamp`	integer	No	—	Start time, ms timestamp
`end_timestamp`	integer	No	—	End time, ms timestamp
`confirm`	string	No	—	Confirmation status: `0` confirmed / `1` unconfirmed / empty for all
`noteType`	string	No	—	Filter by call type (e.g. `call`, `create`)
`ret`	string	No	`all`	Filter by result status (e.g. `SUCCESS`, `REVERT`)
`tokens`	string	No	—	Filter by token ID; multiple IDs separated by commas

Top-level

Field	Type	Required	Description	Unit/Precision
`total`	integer	Required	Total number of matched records	—
`rangeTotal`	integer	Required	Total within the filter range	—
`data`	array	Required	Internal transaction record array, see below	—
`contractMap`	object	Optional	Address → whether it is a contract mapping	—
`contractInfo`	object	Optional	Contract address → label information mapping (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	—

data[] element

Field	Type	Required	Description	Unit/Precision
`hash`	string	Required	External transaction hash that triggered this internal transaction	—
`internal_hash`	string	Required	Internal transaction hash	—
`block`	integer	Required	Block height	—
`timestamp`	integer	Required	Block time	ms timestamp
`from`	string	Required	Sender address	—
`to`	string	Required	Recipient address	—
`call_value`	integer	Required	Call value	sun
`token_id`	string	Required	Token ID (`_` represents TRX)	—
`note`	string	Required	Call type (e.g. `call`, `create`)	—
`confirmed`	boolean	Required	Whether confirmed	—
`rejected`	boolean	Required	Whether rejected	—
`result`	string	Required	Execution result	—
`revert`	boolean	Required	Whether reverted	—
`token_list`	object	Required	Token info; sub-fields see the `token_list` object table below	—
`valueInfoList`	array	Required	Transfer value info list; element schema see the `valueInfoList[]` element table below	—
`toAddressTag`	string	Optional	Recipient address tag (only present when recipient has a tag)	—
`fromAddressTag`	string	Optional	Sender address tag (only present when sender has a tag)	—
`voteToAddress`	array	Required	Vote target address list (empty array for non-vote types)	—
`voteCount`	integer	Required	Vote count (0 for non-vote types)	—
`voteDetail`	array	Required	Vote detail (empty array for non-vote types)	—

token_list object

Field	Type	Required	Description	Unit/Precision
`token_id`	string	Required	Token ID (`_` represents TRX)	—
`call_value`	integer	Required	Call value; sun for TRX, raw token precision for non-TRX assets (convert via `tokenInfo.tokenDecimal`)	—
`tokenInfo`	object	Required	Token metadata (9 common fields; schema shared with `valueInfoList[].tokenInfo` below)	—

valueInfoList[] element

Field	Type	Required	Description	Unit/Precision
`callValue`	integer	Required	Call value; sun for TRX, raw token precision for non-TRX assets (convert via `tokenInfo.tokenDecimal`)	—
`tokenInfo`	object	Required	Token metadata (value schema 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

token_list.tokenInfo / valueInfoList[].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. Key points for this endpoint:

A filter condition must be specified: at least one of address, block, or contract must be provided.
Parameter violations do not produce errors: limit > 50, start + limit > 10000, etc. are silently truncated/capped and return 200.
Empty result is not an error: returns 200 + data: [] when no records match, which is a normal response.