Get Account TRC20 Transfer Records
1. Overview & Typical Use
Query TRC20 token transfer details for a specified account, with support for filtering by direction (outgoing / incoming / approval) and status information.
- Typical use: wallet page displaying a token’s transfer history, distinguishing incoming / outgoing from approval records.
- When not to use: to query all-chain TRC20 transfers use “Get TRC20 & TRC721 Transfer List”; for TRX / TRC10 transfers use “Get TRX & TRC10 Transfer List”.
2. Endpoint & Authentication
GET /api/token_trc20/transfers-with-status
For Base URL and authentication, see Common Network & Authentication.
3. Request
Fields
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start | integer | No | 0 | Start offset; start + limit ≤ 10000, excess is silently handled |
limit | integer | No | 20 | Page size, max 50 (excess is silently truncated) |
trc20Id | string | Yes | — | TRC20 token contract address |
address | string | Yes | — | Account address |
direction | integer | No | 1 | Transfer direction: 1 outgoing, 2 incoming, 0 Approval events |
db_version | integer | No | 0 | Include approval transfers: 1 include, 0 exclude |
reverse | string | No | — | Sort by creation time: true descending, false ascending |
start_timestamp | integer | No | — | Start time, ms timestamp |
end_timestamp | integer | No | — | End time, ms timestamp |
To query unlimited Approval events, set
db_version=1together withdirection=0.
4. Response
Fields
Top-level
| Field | Type | Required | Description | Unit/Precision |
|---|---|---|---|---|
code | integer | Required | Status code (200 = success) | — |
page_size | integer | Required | Number of records returned on the current page | — |
tokenInfo | object | Required | Token metadata (value schema below) | — |
data | array | Required | Transfer record array; see below | — |
contractMap | object | Optional | Address → whether it is a contract mapping | — |
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 | — |
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 | — |
contract_address | string | Required | Token contract address | — |
id | string | Required | Token contract address (same value as contract_address) | — |
amount | string | Required | Transfer quantity (raw string) | Use tokenInfo.tokenDecimal to convert |
status | integer | Required | Transaction status code | — |
approval_amount | string | Required | Approval quantity | — |
approval_amount_unlimited | string | Optional | Unlimited approval flag; value is "unlimited" (present only when approval amount is unlimited) | — |
event_type | string | Required | Event type | — |
confirmed | integer | Required | Confirmation status: 0 unconfirmed, 1 confirmed | — |
contract_type | string | Required | Contract type string (e.g. TriggerSmartContract) | — |
contractType | integer | Required | Contract type number | — |
revert | integer | Required | Whether reverted | — |
contract_ret | string | Required | Contract execution result | — |
final_result | string | Required | Final result | — |
direction | integer | Required | Transfer direction: 1 outgoing, 2 incoming | — |
issue_address | string | Required | Token issuer address | — |
decimals | integer | Required | Token decimals | — |
token_name | string | Required | Token contract name | — |
5. Errors
For HTTP status codes, see Common Errors. Key points for this endpoint:
- Required parameters: both
trc20Idandaddressare required; missing either returns an error. - Parameter violations do not produce errors:
limit > 50,start + limit > 10000, etc. are silently truncated/capped and return200. - Empty result is not an error: no matches returns
200+data: [], which is a normal response.
Last updated on: