REST API / Polymarket / Candlesticks by Token

Candlesticks by Token (Polymarket)

Price history for a single Polymarket outcome token, bucketed at your chosen interval. Prices are not normalized — a NO token charts as NO (e.g. ~$0.30 in a 70/30 market), so you can chart each side of a binary market separately. For traded dollar and share volume, use the Token Volume and Volume Chart endpoints.

GET/v2/polymarket/candlesticks/token/{token_id}

Query Parameters

token_idstring (path)Required

Polymarket outcome token ID (path parameter).

intervalinteger

Bucket size in minutes. Allowed: 0 (auto-pick), 1, 5, 15, 60, 1440. Default: 0.

start_tsinteger

Start of range, unix seconds. Optional.

end_tsinteger

End of range, unix seconds. Optional.

Response Schema

candlesticksobject[]

OHLCV candles in ascending timestamp order.

tinteger

Unix timestamp (seconds) of the bucket start.

onumber

Open — mid-market price (raw token price, not normalized to YES).

hnumber

High — mid-market price for the interval.

lnumber

Low — mid-market price for the interval.

cnumber

Close — mid-market price for the interval.

vnumber | null

Traded volume. Use the Token Volume and Volume Chart endpoints for dollar and share volume.

intervalinteger

Resolved interval in minutes.

interval_secondsinteger

Resolved interval in seconds.

first_trade_tsinteger | null

Earliest timestamp in the response.

last_trade_tsinteger | null

Latest timestamp in the response.

token_idstring

The requested token ID.

_metaobject

Response metadata.

sourcestring

Data source identifier.

volume_availableboolean

Whether traded volume is included in this series.

notestring

Note describing the price series.

Error Responses

All errors return the same envelope. The code field is stable and programmatically branchable; error and message are human-readable. errors[] is present only on validation failures with field-level detail. See the full error code reference →

successboolean

Always `false` on error responses.

errorstring

Short, human-readable title (e.g. 'Invalid API Key.').

messagestring

Human-readable explanation for the error. Safe to surface in UIs.

codestring

Stable, hierarchical machine-readable code (e.g. 'validation.invalid_enum'). Use for programmatic handling.

doc_urlstring

Link to this code's entry in the Error Reference.

errorsobject[]

Optional. Present only on validation failures with field-level detail.

fieldstring

Name of the offending parameter.

codestring

Field-level machine code.

messagestring

Human-readable explanation.

Authentication

API Key

To secure your requests, we strongly recommend passing your API key via the X-API-Key header. This prevents sensitive keys from being exposed in access logs or browser history.

Request HeaderX-API-Key: pmx_test_5e8f...

Rate Limits

API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: requests per second and requests per month. Each completed request counts toward the global monthly quota. Separate endpoint-group monthly limits (matched markets, arbitrage, EV) only advance when the response body has success: true.

Usage is returned on responses via headers such as:

Response Headers (global)X-RateLimit-Limit-Second: 10X-RateLimit-Remaining-Second: 9X-RateLimit-Limit-Month: 1000X-RateLimit-Remaining-Month: 842Example (endpoint-group, when applicable)X-RateLimit-Limit-Arb-Month: 500X-RateLimit-Remaining-Arb-Month: 412

If you exceed a rate limit, the API returns a 429 status with a Retry-After header indicating when you can resume.

Request

Live API Key

Demo Mode

Verified

Parameters

Token IDRequired

Interval (minutes)

Start (unix seconds)

End (unix seconds)

Response

—

Click EXECUTE to send a request →