Get Account Token List
1. Overview & Typical Use
Query the list of tokens held by a specified account with a balance greater than 0. Supports sorting and pagination by token type, price, amount, and more.
- Typical use: account asset list, token holdings display, specific token balance query.
- When not to use: for full account details use “Get Account Detail”; for transfer history use “Get TRC20 Transfer List”.
limitmaximum is 200.
2. Endpoint & Authentication
GET /api/account/tokens
For Base URL and authentication, see Common Network & Authentication.
This endpoint requires an API Key: calls without a Key return 401.
3. Request
Fields
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
address | string | Yes | — | Account address (Base58, starts with T) |
start | integer | No | 0 | Starting offset |
limit | integer | No | 20 | Page size, max 200 |
hidden | integer | No | 0 | Whether to hide small-balance tokens. 0: hide, 1: show |
show | integer | No | 0 | Token type. 0: default, 1: TRC20, 2: TRC721, 3: all, 4: TRC1155 |
sortBy | integer | No | 0 | Sort field. 0: default, 1: price, 2: amount, 3: quantity |
sortType | integer | No | 0 | Sort direction. 0: descending, 1: ascending |
token | string | No | — | Specific token ID or contract address |
assetType | integer | No | 0 | Asset type. 0 or 1: regular tokens, 2: receipt tokens |
showAvailable | integer | No | 0 | Show only tokens with available balance. 1: yes |
tokenType | integer | No | 0 | Token type filter. 0: all; other values per API spec |
card | integer | No | 0 | Return card view data. 1: yes |
4. Response
Fields
Top-level
| Field | Type | Required | Description | Unit/Precision |
|---|---|---|---|---|
total | integer | Required | Total token count | — |
code | integer | Required | Response status code | — |
status | string | Required | Status identifier | — |
message | string | Required | Request result message | — |
lastUpdateSeconds | integer | Required | Last data update time | ms timestamp |
data | array | Required | Token records array; see below | — |
contractMap | object | Required | Address → boolean map of whether it is a contract (always returned, may be empty) | — |
contractInfo | object | Required | Contract address → label info (always returned, may be empty) | — |
data[] elements
| Field | Type | Required | Description | Unit/Precision |
|---|---|---|---|---|
tokenId | string | Required | Token ID (_ for TRX, contract address for TRC20) | — |
tokenName | string | Required | Token name | — |
tokenAbbr | string | Required | Token abbreviation | — |
tokenDecimal | integer | Required | Decimal places | — |
tokenType | string | Required | Token type: trc10 or trc20 (may return trc721/trc1155 when show=2/show=4; actual values per API response) | — |
tokenCanShow | integer | Required | Whether displayable (1: yes) | — |
tokenLogo | string | Required | Token logo URL | — |
tokenLevel | string | Required | Token level: 0 (UNKNOWN), 1 (NEUTRAL), 2 (OK), 3 (SUSPICIOUS), 4 (UNSAFE) | — |
tokenPriceInTrx | number | Optional | Token price in TRX; absent if no price | — |
tokenPriceInUsd | number | Optional | Token price in USD; absent if no price | — |
balance | string | Required | Balance (raw value string) | Requires tokenDecimal to convert |
amount | string | Optional | Converted quantity (decimal string); present when price is available | — |
quantity | number | string | Required | Held quantity (converted); TRX returns a formatted string (e.g. "0.000000"), other tokens return a number | — |
amountInUsd | number | Optional | USD valuation; present when price is available | USD |
realTrxAmountInUsd | number | Optional | Actual TRX-to-USD conversion; present for TRX | USD |
owner_address | string | Optional | Token issuer address (present for both TRC10/TRC20, except TRX) | — |
transferCount | integer | Optional | Total transfer count (except TRX) | — |
nrOfTokenHolders | integer | Optional | Number of holders (except TRX) | — |
vip | boolean | Required | Whether a VIP token | — |
level | string | Optional | Token level: 0 (UNKNOWN), 1 (NEUTRAL), 2 (OK), 3 (SUSPICIOUS), 4 (UNSAFE); present for both TRC10/TRC20, except TRX; defaults to "0" for TRC10 | — |
project | string | Optional | Project name the contract belongs to (TRC20 tokens, available for some projects) | — |
5. Errors
For HTTP status codes, see Common Errors. Notes for this endpoint:
- API Key Required: returns 401 if not provided (see Common Network & Authentication).
- Empty result is not an error: no tokens returns
200+data: [], which is a normal response.
Last updated on: