# Token list (paged)

- Method: `GET`
- Path: `/tokens`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-tokens/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-tokens

## Description

Paginated list of tokens with token_id, coingecko_id, symbol, name, price_usd, market_cap_usd, volume_usd, and address. Sorted by market_cap_usd DESC NULLS LAST by default. Use limit (max 500) and offset for paging.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/tokens' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `limit` (integer, optional): Maximum number of items to return (default and max may vary by endpoint).
- `offset` (integer, optional): Number of items to skip for pagination (use with limit).

## Response

OK

- `limit` (integer): Applied response size limit.
- `offset` (integer): Applied page offset (always 0 for non-paginated token snapshots).
- `tokens` (array<object>): Paged token rows. One entry per indexed token.
- `tokens[].address` (string): Canonical contract address when available; null for native assets or unknown contracts.
- `tokens[].coingecko_id` (string): CoinGecko asset identifier when available; null otherwise.
- `tokens[].market_cap_usd` (number (double)): Latest known market capitalization in USD; null when unavailable.
- `tokens[].mindshare_24h` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].mindshare_change` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].mindshare_change_pct` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].name` (string): Human-readable token name.
- `tokens[].price_usd` (number (double)): Latest known USD price; null when unavailable.
- `tokens[].symbol` (string): Primary trading symbol.
- `tokens[].token_id` (integer (int64)): Internal Nebula token identifier.
- `tokens[].volume_usd` (number (double)): Latest known 24h volume in USD; null when unavailable.
- `total` (integer): Total number of tokens in this response set.

Media type: `application/json`

## JSON Response

```json
{
  "limit": 0,
  "offset": 0,
  "tokens": [
    {
      "address": "string",
      "coingecko_id": "string",
      "market_cap_usd": 0,
      "mindshare_24h": 0,
      "mindshare_change": 0,
      "mindshare_change_pct": 0,
      "name": "string",
      "price_usd": 0,
      "symbol": "string",
      "token_id": 0,
      "volume_usd": 0
    }
  ],
  "total": 0
}
```