Historical data

Copy page

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

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:

{
  "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.

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.