> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Historical data

> Cross-venue OHLCV candles via fetchOHLCV, with honest per-candle provenance and the current per-venue depth.

`GET /api/{exchange}/fetchOHLCV` serves historical price candles for one venue outcome.
History is stored for the 13 venues with a history lane — `pascal`, `xo`, `pred`, and
`predictstreet` have none and answer honestly rather than serving empty
candles — and capture and backfill are availability-dependent.
Predictefy makes no uninterrupted-capture, per-venue freshness, or **growing daily**
guarantee. Request the exact range you need. SX Bet serves captured, trade-derived candles
only; it has no official-history source or catalog-price write-forward coverage.

## Fetching candles

```sh
curl -s "$PREDICTEFY_API_URL/api/polymarket/fetchOHLCV?outcomeId=OUTCOME_ID&resolution=1h&limit=500" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"
```

| Parameter     | Required | Notes                                                                                                                                                                     |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcomeId`   | yes\*    | The catalog `outcomeId` returned by market reads, or the venue-native id (`id` is accepted as an alias).                                                                  |
| `resolution`  | yes      | `1s`/`5s`/`10s`/`30s`: trade-derived for the five venues below. `1m`/`1h`/`1d`: stored. `5m`/`15m`/`30m`/`4h`/`6h`: aggregated (`source: derived`, `sourceType: rollup`). |
| `start`/`end` | no       | ISO timestamp or epoch milliseconds.                                                                                                                                      |
| `limit`       | no       | Up to **5,000 candles per call** — page longer ranges with `start`/`end`.                                                                                                 |

| Venue       | Sub-minute outcomeId format                | Example               |
| ----------- | ------------------------------------------ | --------------------- |
| polymarket  | CLOB asset id                              | `11198861…`           |
| kalshi      | ticker (YES view) / `ticker-NO` (NO view)  | `KXBTC15M-…-00`       |
| hyperliquid | full HIP-4 asset id (venue coin uses `#N`) | `100001730` (`#1730`) |
| sxbet       | `marketHash#outcomeIndex`                  | `0x3f…9a#0`           |
| myriad      | `networkId:marketId:outcomeIdx`            | `42220:1320:0`        |

REST-derived candles use these verbatim catalog formats (the venue-native id is also
accepted):

| Venue      | Catalog outcomeId format                      | Example                                             |
| ---------- | --------------------------------------------- | --------------------------------------------------- |
| predictfun | `predictfun:{marketId}:{indexSet}`            | `predictfun:32153:1`                                |
| limitless  | `{marketSlug}:{yes\|no}`                      | `draw-1784184108504:yes`                            |
| gemini     | `GEMI:{marketId}:{nativeOutcomeId}:{yes\|no}` | `GEMI:NGAS2607312100:GEMI-NGAS2607312100-HI3D2:yes` |

Sub-minute history is forward-only from the start of each venue's capture coverage.
Use `start` and `end` to probe the range you need; empty data means the requested
range predates available capture, contains no trades, or crosses a capture gap. When the
history is unavailable, the route returns retryable `503 HISTORY_UNAVAILABLE`.

`router` is not supported for history — candles are venue-scoped.

## Honest candles

Every candle carries provenance fields so you can distinguish true venue candles from
derived ones:

```json
{
  "timestamp": 1780444800000,
  "open": 0.61,
  "high": 0.63,
  "low": 0.6,
  "close": 0.62,
  "volume": null,
  "source": "write-forward",
  "sourceType": "point-derived",
  "quality": "ok",
  "isTrueCandle": false
}
```

- **`source`** — `official` (venue history API), `onchain`, `write-forward`
  (availability-dependent recorder), or `derived`.
- **`sourceType`** — `true-candle` vs `point-derived` / `trade-derived` / `rest-derived` /
  `book-derived` / `rollup`; `rollup` means query-time aggregation of stored finer candles.
- **`quality`** — `ok`, `partial`, `suspect`, or `mixed`; `mixed` means the bucket aggregates
  inputs of differing quality. Known capture gaps report `partial`: known-damage
  honesty is part of the API contract.
- **`volume`** is `null` where the source doesn't provide it (most point-derived data).

REST-derived candles exist only for Gemini, Predict.fun, and Limitless.
REST-derived candles are served only when stored and streamed candles are both
absent; low-volume accrual is expected. They always report `source: derived`, `sourceType: rest-derived`,
`quality: partial`, and `isTrueCandle: false`. Rollups over a uniformly partial REST base also
report `partial`.

## Coverage depth

The coverage matrix states only what is currently available:

| Venue                      | Current coverage                                                                                                                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Polymarket                 | **Deep official, bounded set:** one-year hourly coverage for a limited market set, plus availability-dependent forward capture. This is not all-market breadth.                         |
| Kalshi                     | **Deep official:** broad hourly backfill plus availability-dependent write-forward capture.                                                                                             |
| Limitless                  | **REST-derived fallback:** minute-and-up candles report `quality: partial`, plus availability-dependent write-forward capture. No stream capture, so sub-minute tiers are honest-empty. |
| Other write-forward venues | Forward-only recording subject to per-venue capture and storage gaps; request the exact range rather than assuming continuous depth.                                                    |
| SX Bet                     | **Captured-tape/derived only:** forward-only trade-derived candles. Minute-and-up tiers derive from the same tape. No official or catalog-price write-forward history is claimed.       |

:::note[No overclaiming]
Official breadth differs by venue: Polymarket covers a bounded market set, while
Kalshi has broader hourly backfill. We never claim the archive is complete or continuously
fresh — if a venue/date range matters to you,
[verify with a request](/quickstart/) or [contact support](mailto:support@predictefy.com).
:::

## Credits

History reads cost a flat **5 credits** per query. During the private beta, every account
receives the full history window. The public plan windows that apply at GA are listed under
[Pricing, credits & billing](/guides/credits/).