Polymarket

Candlesticks

Retrieves past candlestick data for a token associated with a market given token_id across a specified time interval.

POST/v2/semantic/retrieve/parameterized

Query Parameters

token_idstring

Blockchain token identifier for the specific market outcome

Example:

"58639447033085668146701215689433308999613524738987821507545529427932862502961"

intervalstring

Interval of the candlestick. Possible values are 1m 5m 15m 1h 4h 1d 1w .

There are range limits for interval and the end_time will be capped:

1m: max range 7 days
5m: max range 15 days
15m: max range 30 days
1h: max range 90 days
4h: max range 180 days
1d: max range 360 days
1w: max range 360 days

Example:

"1m"

start_timestring

Filter after this timestamp

Example:

"1769219100"

end_timestring

Filter before this timestamp

Example:

"1769508420"

Response Fields

Field	Type	Description
`candle_time`	String (ISO 8601)	Timestamp representing the start time of the candlestick interval
`open`	String (Decimal)	Opening price for the interval
`high`	String (Decimal)	Highest traded price during the interval
`low`	String (Decimal)	Lowest traded price during the interval
`close`	String (Decimal)	Closing price for the interval
`mean`	String (Decimal)	Mean (average) traded price during the interval
`volume`	String (Decimal)	Total traded volume during the interval
`trade_count`	Integer	Number of trades executed during the interval
`outcome`	String	Market outcome this candlestick represents (e.g., `Yes`, `No`)
`condition_id`	String	Ethereum condition ID identifying the underlying market
`token_id`	String	Blockchain token identifier for the specific market outcome
`ask_open`	String (Decimal)	Opening ask price for the interval
`ask_high`	String (Decimal)	Highest ask price during the interval
`ask_low`	String (Decimal)	Lowest ask price during the interval
`ask_close`	String (Decimal)	Closing ask price for the interval
`bid_open`	String (Decimal)	Opening bid price for the interval
`bid_high`	String (Decimal)	Highest bid traded price during the interval
`bid_low`	String (Decimal)	Lowest bid price during the interval
`bid_close`	String (Decimal)	Closing bid price for the interval
`spread`	String (Decimal) \	null	Bid-ask spread (ask_close − bid_close). `null` when either side is unavailable.

Tips for Best Results

•Limit the duration with proper start_time and end_time. Use shorter intervals for shorter durations, such as 1m or 5m

Candlesticks

curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 568,
  "params": {
    "token_id": "58639447033085668146701215689433308999613524738987821507545529427932862502961",
    "interval": "1m",
    "start_time": "1769219100",
    "end_time": "1769508420"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'

200Example response

{
  "timestamp": "",
  "params": {
    "end_time": "1770083100",
    "interval": "4h",
    "start_time": "1769910300",
    "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "ask_close": "0.5100",
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": "0.9900",
        "bid_close": "0.5000",
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": "0.0100",
        "candle_time": "2026-02-01T00:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5033",
        "open": "0.5000",
        "outcome": "No",
        "spread": "0.0100",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 6,
        "volume": "135.97"
      },
      {
        "ask_close": "0.5100",
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": "0.9900",
        "bid_close": "0.5000",
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": "0.0100",
        "candle_time": "2026-02-01T04:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5038",
        "open": "0.5000",
        "outcome": "No",
        "spread": "0.0100",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 15,
        "volume": "1020.08"
      }
    ]
  },
  "request_id": ""
}