> For the complete documentation index, see [llms.txt](https://docs.dexpal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dexpal.io/for-partners/endpoints/dex-token.md).

# DEX Token

Returns data about the DEX's governance or platform token. Omit this endpoint entirely if the DEX has no token.

## Overview

|                    |                 |
| ------------------ | --------------- |
| **Method**         | GET             |
| **Poll frequency** | Every 5 minutes |
| **Auth**           | Bearer API key  |
| **Rate limit**     | 60 req/min      |

## Request

No query parameters.

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | yes      | `Bearer <api_key>` |

## Response

Returns a single `data` object with token market data.

### Fields — Token Object

| Field               | Type    | Required | Description                                                         |
| ------------------- | ------- | -------- | ------------------------------------------------------------------- |
| `ticker`            | string  | yes      | Token ticker symbol e.g. `"GNS"`.                                   |
| `marketPrice`       | number  | yes      | Current live market price in USD.                                   |
| `marketCap`         | number  | no       | Current market capitalisation in USD (circulating supply × price).  |
| `fullyDilutedMcap`  | number  | no       | Fully diluted market cap in USD (total supply × price).             |
| `volume24h`         | number  | no       | 24-hour token trading volume in USD.                                |
| `tvl`               | number  | no       | Total value locked attributed to the token (staking, pools) in USD. |
| `circulatingSupply` | number  | no       | Current circulating supply in token units.                          |
| `totalSupply`       | number  | no       | Total minted supply in token units.                                 |
| `maximumSupply`     | number  | no       | Maximum possible supply in token units. `null` if uncapped.         |
| `priceAth`          | object  | no       | All-time high price record. See below.                              |
| `priceAtl`          | object  | no       | All-time low price record. See below.                               |
| `holdersCount`      | integer | no       | Number of unique wallet addresses holding the token.                |
| `tokenStakedPct`    | number  | no       | Percentage of total supply currently staked (0–100).                |
| `tokenStakingApy`   | number  | no       | Current staking APY as a decimal percentage.                        |

### Fields — PriceRecord Object (`priceAth`, `priceAtl`)

| Field   | Type    | Required | Description                 |
| ------- | ------- | -------- | --------------------------- |
| `value` | number  | yes      | Price in USD at the record. |
| `date`  | ISO8601 | yes      | Date the record was set.    |

## Example Response

```json
{
  "success": true,
  "data": {
    "ticker": "GNS",
    "marketPrice": 1.93,
    "marketCap": 64661108,
    "fullyDilutedMcap": 64602278,
    "volume24h": 2197147,
    "tvl": 14755122,
    "circulatingSupply": 33394127,
    "totalSupply": 33394127,
    "maximumSupply": null,
    "priceAth": { "value": 12.45, "date": "2023-02-17T00:00:00Z" },
    "priceAtl": { "value": 0.259, "date": "2021-11-29T00:00:00Z" },
    "holdersCount": 158296,
    "tokenStakedPct": 45.5,
    "tokenStakingApy": 12.5
  },
  "timestamp": "2026-01-20T21:00:00Z"
}
```

## Error Responses

| Status | Error                                 | When                      |
| ------ | ------------------------------------- | ------------------------- |
| `401`  | `"Invalid or missing API key"`        | Bad or absent auth header |
| `404`  | `"No token associated with this DEX"` | DEX has no platform token |
| `500`  | `"Internal server error"`             | Unexpected failure        |

## Notes

* If `circulatingSupply` equals `totalSupply`, both fields are still required separately.
* `tokenStakedPct` and `tokenStakingApy` should match the values returned in [`metrics`](/for-partners/endpoints/dex-metrics.md) if both endpoints are implemented.
* Return `"maximumSupply": null` explicitly for tokens with no hard cap (do not omit the field).