# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.