# 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';
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/reservoir/schema-reference/candles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.