> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/reservoir/schema-reference/candles.md).

# Candles

1-second OHLCV candlestick data for every perpetual and spot market on Hyperliquid and all HIP-3 dexes. Updated daily. Larger intervals (1m, 5m, 1h, etc.) can be aggregated from the 1s data.

## S3 Paths

**Bucket:** `s3://hydromancer-reservoir` (requester pays)

```
global/candles/1s/date=YYYY-MM-DD/candles.parquet
by_dex/{dex}/candles/1s/date=YYYY-MM-DD/candles.parquet
```

Files are only created for dates with data. Each file contains all markets for that dex on that day.

## Schema

| Column         | Type               | Description                                             |
| -------------- | ------------------ | ------------------------------------------------------- |
| `coin`         | string             | Raw market identifier (e.g., `BTC`, `xyz:MSFT`, `@107`) |
| `dex`          | string             | DEX name                                                |
| `asset_class`  | string             | `perp` or `spot`                                        |
| `base_symbol`  | string             | Base asset (e.g., `BTC`, `MSFT`)                        |
| `quote_symbol` | string             | Quote/collateral asset (e.g., `USDC`, `USDT0`)          |
| `timestamp`    | timestamp(ms, UTC) | Candle open time                                        |
| `open`         | decimal(20,10)     | Open price                                              |
| `high`         | decimal(20,10)     | High price                                              |
| `low`          | decimal(20,10)     | Low price                                               |
| `close`        | decimal(20,10)     | Close price                                             |
| `volume`       | decimal(20,10)     | Volume in base asset                                    |
| `volume_quote` | decimal(20,10)     | Volume in quote asset                                   |
| `trade_count`  | uint32             | Number of trades                                        |

## Aggregating to Larger Intervals

Since we provide 1s candles, you can aggregate to any interval:

```sql
-- 1-minute candles from 1s data
SELECT
    coin,
    time_bucket(INTERVAL '1 minute', timestamp) as minute,
    first(open) as open,
    max(high) as high,
    min(low) as low,
    last(close) as close,
    sum(volume) as volume,
    sum(volume_quote) as volume_quote,
    sum(trade_count) as trade_count
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/candles/1s/date=2026-03-22/candles.parquet')
WHERE coin = 'BTC'
GROUP BY coin, minute
ORDER BY minute;

-- 1-hour candles
SELECT
    coin,
    time_bucket(INTERVAL '1 hour', timestamp) as hour,
    first(open) as open,
    max(high) as high,
    min(low) as low,
    last(close) as close,
    sum(volume) as volume,
    sum(volume_quote) as volume_quote,
    sum(trade_count) as trade_count
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/candles/1s/date=2026-03-22/candles.parquet')
WHERE coin = 'ETH'
GROUP BY coin, hour
ORDER BY hour;
```

## Quick Start

### DuckDB

```sql
INSTALL httpfs;
LOAD httpfs;
SET s3_region = 'ap-northeast-1';

-- BTC 1s candles for a day
SELECT timestamp, open, high, low, close, volume, trade_count
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/candles/1s/date=2026-03-22/candles.parquet')
WHERE coin = 'BTC'
ORDER BY timestamp;

-- Most traded markets by quote volume
SELECT base_symbol, dex, sum(volume_quote) as total_volume
FROM read_parquet('s3://hydromancer-reservoir/global/candles/1s/date=2026-03-22/candles.parquet')
GROUP BY base_symbol, dex
ORDER BY total_volume DESC
LIMIT 20;

-- Multi-day query
SELECT *
FROM read_parquet('s3://hydromancer-reservoir/by_dex/xyz/candles/1s/date=*/candles.parquet')
WHERE coin = 'xyz:MSFT'
  AND timestamp >= '2026-03-20' AND timestamp < '2026-03-23';
```