> For the complete documentation index, see [llms.txt](https://docs.sfox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sfox.com/rest-api/market-data/get-candlesticks.md).

# Get Candlesticks

<mark style="color:green;">**`GET`**</mark> `https://chartdata.sfox.com/candlesticks`

Retrieve historical candlestick / OHLCV (Open-High-Low-Close-Volume) data for a currency pair. Returns an array of objects, each representing a candle.

{% hint style="info" %}

* Data represents aggregated trades data from all of sFOX's supported liquidity providers. NOT representative of trades executed on sFOX.
* Data is not forward-filled and, therefore, may be incomplete. e.g. no data will be returned for an interval during which 0 trades were recorded.
  {% endhint %}

{% hint style="warning" %}
**Responses are limited to 500 candles.** If the requested `startTime` , `endTime` , and `period` will result in more than 500 data points, your request will be rejected. To retrieve data over a larger time range, you will need to make multiple requests with new `startTime` / `endTime` ranges. Candles may precede your specified `startTime` value.
{% endhint %}

### Query Parameters

<table><thead><tr><th width="244">Parameter</th><th width="145">Type</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>pair</code></strong> <mark style="color:red;">required</mark></td><td>string</td><td>Specify the currency pair to retrieve data for. e.g. <code>btcusd</code></td></tr><tr><td><strong><code>startTime</code></strong> <mark style="color:red;">required</mark></td><td>timestamp</td><td>The unix timestamp (seconds) of the first datapoint returned</td></tr><tr><td><strong><code>endTime</code></strong> <mark style="color:red;">required</mark></td><td>timestamp</td><td>The unix timestamp (seconds) of the last datapoint you want returned</td></tr><tr><td><strong><code>period</code></strong></td><td>int</td><td><p>The duration or interval of each datapoint or candle in seconds (e.g. <code>period</code> = <code>60</code> would return 1-minute candles). Possible values:</p><ul><li><code>60</code> (1 minute) default if not specified</li><li><code>300</code> (5 minute)</li><li><code>900</code> (15 minute)</li><li><code>3600</code> (1 hour)</li><li><code>21600</code> (6 hour)</li><li><code>86400</code> (1 day)</li></ul></td></tr></tbody></table>

### Response Body

<table><thead><tr><th width="218">Key</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>open_price</code></strong></td><td>The price of the first trade recorded after the <code>start_time</code></td></tr><tr><td><strong><code>high_price</code></strong></td><td>The highest trade price during this period</td></tr><tr><td><strong><code>low_price</code></strong></td><td>The lowest trade price during this period</td></tr><tr><td><strong><code>close_price</code></strong></td><td>The price of the last trade executed in this period</td></tr><tr><td><strong><code>volume</code></strong></td><td>Total base currency volume traded during this period</td></tr><tr><td><strong><code>start_time</code></strong></td><td>The unix timestamp of the beginning of the period</td></tr><tr><td><strong><code>pair</code></strong></td><td>The trading pair / symbol</td></tr><tr><td><strong><code>candle_period</code></strong></td><td>The duration of each datapoint in seconds</td></tr><tr><td><strong><code>vwap</code></strong></td><td>The volume-weighted average price of the period</td></tr><tr><td><strong><code>trades</code></strong></td><td>The total number of trades executed across all liquidity providers during that period</td></tr></tbody></table>

### Responses

<details>

<summary><mark style="color:green;">200</mark></summary>

```json
[
  {
    "open_price":"9654",
    "high_price":"9662.37",
    "low_price":"9653.66",
    "close_price":"9655.73",
    "volume":"6.31945755",
    "start_time":1592939280,
    "pair":"btcusd",
    "candle_period":60,
    "vwap":"9655.70504211",
    "trades":53
  }
]
```

</details>

### Example Request

{% tabs %}
{% tab title="Shell" %}
{% code overflow="wrap" %}

```bash
curl 'https://chartdata.sfox.com/candlesticks?endTime=1665165809&pair=btcusd&period=86400&startTime=1657217002'
```

{% endcode %}
{% endtab %}

{% tab title="NodeJS" %}

```javascript
const axios = require('axios');

axios({
  method: 'get',
  url: 'https://chartdata.sfox.com/candlesticks',
  params: {
    pair: 'btcusd',
    startTime: 1657217002,
    endTime: 1665165809,
    period: 86400
  }
}).then(response => {
  console.log(response)
}).catch(err => {
  console.error(err)
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

data = requests.get(
  "https://chartdata.sfox.com/candlesticks",
  headers={
    "Authorization": "Bearer <API_KEY>",
  },
  params={
   "pair":"btcusd",
   "startTime": 1657217002,
   "endTime": 1665165809,
   "period": 86400
  }
)
print(data)
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sfox.com/rest-api/market-data/get-candlesticks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.