---
title: Candles & Funding
description: Historical OHLCV and funding rates from immutable dataset releases.
---

Both endpoints read from validated, checksummed dataset releases — the same bytes the backtest engine uses. Coverage per venue/pair is in [`/context/datasets`](/context/datasets).

### GET /context/candles

**Query parameters**

| Param | Type | Notes |
|---|---|---|
| `venue` | string | Required |
| `symbol` | string | Required — the canonical `symbol` exactly as returned by [`/context/markets`](/context/markets) (never a framework alias) |
| `timeframe` | string | `1m`, `5m`, `15m`, `1h`, `4h`, `1d` (aggregated server-side from 1m) |
| `from` / `to` | ISO 8601 | Required window; max 10,000 candles per request |
| `cursor` | string | Continue a windowed read |
| `release` | string | Optional immutable release id; continuation cursors pin this automatically |

**Response — `200`**

```json
{
  "venue": "lighter",
  "symbol": "SOL-PERP.LIGHTER",
  "timeframe": "1h",
  "release": "rel_2026-07-27T02",
  "candles": [
    { "t": "2026-07-01T00:00:00Z", "o": 141.22, "h": 143.05, "l": 140.9, "c": 142.71, "v": 183422.5 }
  ],
  "gaps": [],
  "next_cursor": null
}
```

- `release` pins the immutable dataset release the rows came from — quote it and any re-read returns identical bytes. On venues whose release pipeline is still pending (Hyperliquid, Binance — see [datasets](/context/datasets)), `release` is `null` and reproducibility is not claimed.
- `gaps` lists intervals **the venue itself never served** (venue-side holes are recorded, never interpolated). An empty array is a completeness statement, not a default.
- Bulk export: send `Accept: text/csv` for the same window as CSV — one row per candle, same fields. CSV page metadata is returned in stable response headers: `X-Superior-Context-Venue`, `X-Superior-Context-Symbol`, `X-Superior-Context-Timeframe`, `X-Superior-Context-Release`, `X-Superior-Context-Gaps`, and `X-Superior-Next-Cursor`. The bounded gaps header is an unpadded base64url JSON summary with `state` (`unknown`, `complete`, or `present`), `count`, and—when known—a SHA-256 fingerprint of the ordered gap ledger; request JSON for the full gap entries. Release and next-cursor headers use the literal `null` when absent; otherwise pass `X-Superior-Next-Cursor` back as `cursor` to continue.

### GET /context/funding

Hourly funding rates for perp venues.

**Query parameters:** `venue`, `symbol`, `from`, `to`, `limit`, `cursor`, and `release` (same semantics as candles, without `timeframe`). CSV uses the same metadata headers except `X-Superior-Context-Timeframe`.

**Response — `200`**

```json
{
  "venue": "lighter",
  "symbol": "SOL-PERP.LIGHTER",
  "release": "rel_2026-07-27T02",
  "fundings": [
    {
      "t": "2026-07-01T00:00:00Z",
      "rate": 0.0000125,
      "rate_annualized": 0.1095
    }
  ],
  "gaps": [
    { "from": "2025-01-21T14:00:00Z", "to": "2025-01-21T15:00:00Z", "reason": "venue_history_hole" }
  ]
}
```

`rate` is the decimal fraction per funding interval; `rate_annualized` is derived for convenience. Funding history is the input for carry analysis and cost-of-hold modeling — the things a directional backtest silently ignores.

## Freshness

Releases publish on backfill cadence (hourly for active venues), so the most recent ~1–2 hours may not be in a release yet. `to` values beyond the latest release are clamped, and the response's `release` timestamp tells you the effective horizon. Context is a research surface; execution-time data belongs to your deployed framework's live venue connection.