Address tokens
List the known token balances (for example USDT, USDC) of an ETH or TRON address.
# Address tokens
`GET https://api.rarebl.com/open/address/tokens` or `POST https://api.rarebl.com/open/address/tokens`
Token balances held by an ETH or TRON address: known tokens such as USDT and USDC, plus TRC-10 assets on TRON.
**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.
## Request
Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.
Example: `curl "https://api.rarebl.com/open/address/tokens?chain=tron&address=TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"`
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. Tokens exist on eth and tron only. One of: eth, tron. |
| `address` | string | Yes | The ETH or TRON address. ETH: 0x + 40 hex. TRON: base58, starting with T. |
## Responses
### API200 (HTTP 200): OK
Token balances of a TRON address (shortened). TRC-10 assets have no symbol, name or decimals.
```json
{
"status": 1,
"code": "API200",
"message": "success",
"data": {
"tokens": [
{
"contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"standard": "TRC-20",
"symbol": "USDT",
"name": "Tether USD",
"decimals": 6,
"balance": "0.00698"
},
{
"contract": "1004989",
"standard": "TRC-10",
"symbol": null,
"name": null,
"decimals": null,
"balance": "1111111"
},
{
"contract": "1005119",
"standard": "TRC-10",
"symbol": null,
"name": null,
"decimals": null,
"balance": "8888"
}
]
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
| Field | Type | Description |
| --- | --- | --- |
| `data.tokens[].contract` | string | Token contract address. |
| `data.tokens[].standard` | string | ERC-20, ERC-721, ERC-1155, TRC-20, TRC-721 or TRC-10. |
| `data.tokens[].symbol / name` | string \| null | Token symbol and name when known. |
| `data.tokens[].decimals` | integer \| null | Token decimals. |
| `data.tokens[].balance` | string | Balance as a decimal string in whole token units. |
### API400 (HTTP 400): Bad Request
A parameter is missing or malformed. `data.param` names it (here `chain`).
```json
{
"status": 0,
"code": "API400",
"message": "Tokens exist on eth and tron only.",
"data": {
"param": "chain"
},
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API429 (HTTP 429): Too Many Requests
Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.
```json
{
"status": 0,
"code": "API429",
"message": "Too many requests. Please retry shortly.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
### API502 (HTTP 502): Bad Gateway
The node is unavailable, still syncing or timed out. Retry later with a short back-off.
```json
{
"status": 0,
"code": "API502",
"message": "The node is unavailable or timed out. Please try again.",
"data": null,
"go": null,
"meta": {
"requestid": "0123456789abcdef",
"notices": []
}
}
```
## Notes
- Only known tokens are returned for now (for example USDT and USDC), not every token the address ever touched. On TRON, TRC-10 assets are listed too, with `symbol`, `name` and `decimals` null.
- An empty `tokens` array means none of the known tokens are held.