Candles
Returns OHLCV (Open, High, Low, Close, Volume) candlestick data for any token. Powered by TimescaleDB continuous aggregates that automatically roll up raw trades into 1-minute, 5-minute, 1-hour, and 1-day buckets.
Endpoint
GET /api/candles/:tokenAddress
Path Parameters
| Parameter | Type | Description |
|---|
tokenAddress | string | CW20 contract address of the token |
Query Parameters
| Parameter | Type | Default | Description |
|---|
timeframe | string | "1h" | Candle interval: "1m", "5m", "1h", "1d" |
from | string | 24h ago | Start time (ISO 8601 with timezone, e.g., 2026-02-18T00:00:00Z) |
to | string | now | End time (ISO 8601 with timezone) |
limit | number | 300 | Maximum candles to return (1-1000) |
Examples
# Last 24 hours of 1-hour candles (default)
curl http://67.205.164.156:3001/api/candles/xyz1cw20contract...
# Last 7 days of daily candles
curl "http://67.205.164.156:3001/api/candles/xyz1cw20contract...?timeframe=1d&from=2026-02-12T00:00:00Z"
# Last 2 hours of 5-minute candles
curl "http://67.205.164.156:3001/api/candles/xyz1cw20contract...?timeframe=5m&from=2026-02-19T08:00:00Z&limit=24"
Response
{
"token_address": "xyz1cw20contract...",
"timeframe": "1h",
"candles": [
{
"time": "2026-02-19T08:00:00.000Z",
"open": "50000",
"high": "55000",
"low": "48000",
"close": "52000",
"volume": "250000000000",
"trade_count": 47
},
{
"time": "2026-02-19T09:00:00.000Z",
"open": "52000",
"high": "58000",
"low": "51000",
"close": "56000",
"volume": "180000000000",
"trade_count": 31
}
]
}
Response Fields
| Field | Type | Description |
|---|
time | string | Start of the candle period (ISO 8601) |
open | string | Price at the start of the period (uxyz per token, scaled by 10^6) |
high | string | Highest price during the period |
low | string | Lowest price during the period |
close | string | Price at the end of the period |
volume | string | Total XYZ trading volume during the period (in uxyz) |
trade_count | number | Number of trades during the period |
Price Conversion
All price values are in uxyz per token, scaled by 10^6:
"close": "52000" → 52000 / 10^6 = 0.052 uxyz per micro-token
→ 0.052 XYZ per token
Volume Conversion
Volume is in uxyz:
"volume": "250000000000" → 250000000000 / 10^6 = 250,000 XYZ
Timeframe Details
| Timeframe | Bucket Size | Best For | Data Retention |
|---|
1m | 1 minute | Scalping, live charts | 90 days |
5m | 5 minutes | Short-term trading | 90 days |
1h | 1 hour | Daily analysis | 90 days |
1d | 1 day | Long-term trends | 90 days |
Periods with no trades will be missing from the response (no zero-volume candles). If you need a continuous series for charting, fill gaps client-side using the previous candle’s close price.
Errors
| Status | Condition |
|---|
400 | Invalid query parameters (bad timeframe, unparseable date, limit out of range) |
500 | Internal server error |
