# GET /token/top

**Operation ID:** `GetTopTokens`

Get top tokens by exchange activity

Analyzes token activity across centralized and decentralized exchanges. Ranks tokens by volume, inflows, outflows, netflows, and other metrics over customizable time intervals.

Supports filtering by chain, market cap, and specific tokens.

Each result reports 'current' (metrics over the selected timeframe) and 'previous' (the same metrics averaged across the numReferencePeriods prior windows, each the length of the timeframe); the two are compared to produce the change and percentage rankings.

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `timeframe` | query | string | Yes | Time interval for aggregation. Example: `"1h"` |
| `orderByAgg` | query | string | Yes | Metric to sort by. Example: `"volume"` |
| `orderByDesc` | query | boolean | Yes | Sort order. Use 'true' for descending, 'false' for ascending. Example: `true` |
| `orderByPercent` | query | boolean | Yes | If 'true', sort by percentage change rather than absolute values. Example: `true` |
| `from` | query | string | Yes | Pagination offset (starting index). Example: `"0"` |
| `size` | query | string | Yes | Number of results to return per page. Example: `"50"` |
| `minVolume` | query | string | No | Minimum volume filter in USD. Example: `"1000000"` |
| `maxVolume` | query | string | No | Maximum volume filter in USD. Example: `"1000000000"` |
| `minMarketCap` | query | string | No | Minimum market cap filter in USD. Example: `"1000000"` |
| `maxMarketCap` | query | string | No | Maximum market cap filter in USD. Example: `"10000000000000"` |
| `numReferencePeriods` | query | string | No | Number of prior periods (each the length of the timeframe) used as the historical baseline the current period is compared against. Default: auto (6 periods for 1h, 1 for longer timeframes). Max: 10. Example: `"auto"` |
| `tokenIds` | query | string | No | Comma-separated list of CoinGecko token IDs to filter results. Example: `"usd-coin,tether"` |
| `chains` | query | array | No | Chains to filter by, as a single comma-separated string, e.g. 'ethereum,bsc' (not a JSON array). If omitted, returns all supported chains. Example: `["ethereum","bsc","polygon"]` |

## Responses

- **200**: OK
  **Schema**: ([GetTopTokensResponse](https://arkm.com/llms/schemas/GetTopTokensResponse.md))

**Example:**
```json
{
  "tokens": [
    {
      "current": {
        "inflowCexVolume": 181200000,
        "inflowDexVolume": 152300000,
        "outflowCexVolume": 179400000,
        "outflowDexVolume": 151800000,
        "price": 0.999831
      },
      "previous": {
        "inflowCexVolume": 176500000,
        "inflowDexVolume": 148100000,
        "outflowCexVolume": 175300000,
        "outflowDexVolume": 149200000,
        "price": 0.999797
      },
      "token": {
        "id": "usd-coin",
        "marketCap": 73340976893,
        "symbol": "USDC"
      }
    }
  ],
  "total": 8189
}
```
- **400**: Bad Request
- **500**: Internal Server Error

## Example

```bash
curl -X GET "https://api.arkm.com/token/top?timeframe=1h&orderByAgg=volume&orderByDesc=true&orderByPercent=true&from=0&size=50&minVolume=1000000&maxVolume=1000000000&minMarketCap=1000000&maxMarketCap=10000000000000&numReferencePeriods=auto&tokenIds=usd-coin,tether&chains=ethereum,bsc,polygon" \
  -H "API-Key: YOUR_API_KEY"
```