## GET /openapi/v1/dex/tokens/history

One DEX token's price candles — open, high, low, close, volume and traders — by day or by hour.

### Query parameters

| Parameter | Type | Default | Notes |
|:--|:--|:--|:--|
| `chain_slug`, `address` | string | required | See [naming a token](#dex-tokens-what-the-endpoints-share); there is no `id` |
| `interval`, `time_start`, `time_end` | string | `1d`, none, now | See [History: what the endpoints share](#history-what-the-endpoints-share) |

### Response

```json
{
  "code": 0,
  "message": "success",
  "message_key": "SUCCESS",
  "result": {
    "chain_slug": "base",
    "address": "0x07b3d902783c3c12b077508c3b5c00113d1291d0",
    "interval": "1d",
    "points": [
      {
        "time": "2026-10-19T00:00:00Z",
        "open": "0.0198",
        "high": "0.0211",
        "low": "0.0195",
        "close": "0.0201",
        "volume": "251340211.4",
        "traders": 3120
      }
    ]
  }
}
```

The candles are copied from our DEX data once an hour. Recent candles are not final: the newest
may still be open — today's daily candle, this hour's hourly one — and a closed one can be
corrected by a later copy when our source repairs it.
Daily candles go back as far as we have them, hourly ones 90 days. Not every token has candles:
one we know without any answers `200` with `points: []`. A token that has left the lists keeps
the candles already stored, and the endpoint still answers for it. Unlike the other `/dex`
endpoints, this one does not depend on the age of the Trending list.

| Field | Type | Notes |
|:--|:--|:--|
| `chain_slug`, `address`, `interval` | string | As asked; an address shaped `0x` + 40 hexadecimal digits lower-cased |
| `points[].time` | string | The candle's open time, RFC3339. A daily candle's open time is the one our source gives it, which is not necessarily midnight UTC |
| `points[].open`, `high`, `low`, `close` | string | USD, never `null` |
| `points[].volume` | string | Traded value in USD, never `null` |
| `points[].traders` | number or `null` | How many traders; `null` when the source has no count |

There is no FDV. Our website's DEX chart has more intervals (`5m`, `4h`) and fills a gap by
carrying the last close forward as a flat, zero-volume candle; this endpoint has only `1d` and
`1h`, and leaves gaps empty.

### Examples

```bash
curl -H "X-Api-Key: <your-api-key>" \
  "https://open-api.coinworldcap.com/openapi/v1/dex/tokens/history?chain_slug=base&address=0x07b3d902783c3c12b077508c3b5c00113d1291d0"
```

| HTTP status | `code` | When |
|:--|:--|:--|
| 400 | 40000 | `chain_slug` or `address` missing; `interval`, `time_start` or `time_end` not as [History](#history-what-the-endpoints-share) allows; more than 1,000 points in the range |
| 404 | 40400 | We know no such token on that chain — retrying will not help |
| 503 | 50300 | Reading the token or its candles timed out (retryable) |
| 500 | 50000 | Reading the token or its candles failed for another reason |

The other errors are in [Errors](#errors).