> ## Documentation Index
> Fetch the complete documentation index at: https://molelcule.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Candles and Price History for Prediction Markets API

> Query candlestick OHLCV data and tick-level price history for prediction market instruments using the Molecule candles and prices API.

The `markets.candles()` and `markets.prices()` methods give you access to historical price data for any prediction market instrument available through Molecule. Use `candles()` to retrieve OHLCV-formatted candlestick series suitable for charting or model inputs, and `prices()` to pull tick-level or interval-aggregated price history for more granular analysis.

***

## markets.candles

Retrieve OHLCV candlestick data for a venue instrument. Each candle contains open, high, low, close, and volume values for the specified time interval. Use this for charting, backtesting, and time-series model inputs.

```python theme={"dark"}
import os
from molecule import Molecule

client = Molecule(
    base_url=os.environ["MOLECULE_BASE_URL"],
    key_id=os.environ["MOLECULE_KEY_ID"],
    private_key=os.environ["MOLECULE_PRIVATE_KEY"],
)

candles = client.markets.candles(
    instrument_id=42,
    interval="1h",
    limit=500,
)

for candle in candles:
    print(candle["t"], candle["o"], candle["h"], candle["l"], candle["c"], candle["v"])
```

**Endpoint:** `GET /v1/candles`

<ParamField query="instrument_id" type="integer" required>
  The venue-specific instrument ID to retrieve candles for.
</ParamField>

<ParamField query="interval" type="string" default="1h">
  Candle interval. Common values: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. Defaults to `1h`.
</ParamField>

<ParamField query="limit" type="integer" default="500">
  Maximum number of candles to return. Defaults to `500`. Candles are ordered from oldest to newest.
</ParamField>

<Tip>
  For high-frequency model inputs, use shorter intervals such as `1m` or `5m` with a larger `limit`. For strategy backtesting over longer horizons, use `1h` or `1d` intervals.
</Tip>

***

## markets.prices

Retrieve tick-level or interval-aggregated price history for a venue instrument. Use `type="ticks"` to get individual price points as they occurred, or specify an interval to receive bucketed price data.

```python theme={"dark"}
prices = client.markets.prices(
    instrument_id=42,
    type="ticks",
    limit=100,
    interval="1h",
)

for point in prices:
    print(point["timestamp"], point["price"])
```

**Endpoint:** `GET /v1/prices`

<ParamField query="instrument_id" type="integer" required>
  The venue-specific instrument ID to retrieve price history for.
</ParamField>

<ParamField query="type" type="string" default="ticks">
  Price series type. Use `ticks` for individual price events. Other values may represent aggregated series depending on venue support.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum number of price records to return. Defaults to `100`.
</ParamField>

<ParamField query="interval" type="string" default="1h">
  Time bucketing interval for aggregated price series. Relevant when `type` is not `ticks`.
</ParamField>

<CodeGroup>
  ```python Tick-level prices theme={"dark"}
  prices = client.markets.prices(
      instrument_id=42,
      type="ticks",
      limit=200,
  )

  for point in prices:
      print(point["timestamp"], point["price"])
  ```

  ```python Interval prices theme={"dark"}
  prices = client.markets.prices(
      instrument_id=42,
      type="interval",
      interval="5m",
      limit=100,
  )

  for point in prices:
      print(point["timestamp"], point["price"])
  ```
</CodeGroup>

<Info>
  `markets.prices()` and `markets.candles()` both provide historical price data but serve different use cases. Use `candles()` when you need OHLCV structure (for example, to compute indicators or render charts). Use `prices()` when you need raw price events or a flat time-series of values.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.