# Token

`GET https://api.rarebl.com/open/token/info` or `POST https://api.rarebl.com/open/token/info`

Metadata of a token contract on ETH or TRON: standard, name, symbol, decimals and total supply.

**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/token/info?chain=tron&contract=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. Tokens exist on eth and tron only. One of: eth, tron. |
| `contract` | string | Yes | The token contract address. ETH: 0x + 40 hex. TRON: base58, starting with T. |

## Responses

### API200 (HTTP 200): OK

Metadata of the TRC-20 USDT contract on TRON (`details` shortened).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "token": {
      "chain": "tron",
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "standard": "TRC-20",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "totalSupply": "94207597532.054777",
      "holders": null,
      "transfers": null,
      "details": [
        {
          "key": "standard",
          "label": "Standard",
          "value": "TRC-20",
          "kind": "text"
        },
        {
          "key": "contract",
          "label": "Contract",
          "value": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "kind": "address"
        },
        {
          "key": "decimals",
          "label": "Decimals",
          "value": 6,
          "kind": "number"
        }
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.token.standard` | string | ERC-20, ERC-721, ERC-1155, TRC-20, TRC-721 or TRC-10. |
| `data.token.name / symbol` | string \| null | Token name and symbol. |
| `data.token.decimals` | integer \| null | Token decimals. |
| `data.token.totalSupply` | string \| null | Total supply in whole token units. |
| `data.token.holders / transfers` | integer \| null | Null until the history index exists. |

### 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": []
  }
}
```

### API404 (HTTP 404): Not Found

The token does not exist on that chain.

```json
{
  "status": 0,
  "code": "API404",
  "message": "No contract at this address.",
  "data": null,
  "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

- `holders` and `transfers` are null today: they need the history index.