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

# GET /forex/prices

> Historical OHLCV candlestick data for a forex pair

## Endpoint

```
GET https://api.marketdataset.ai/forex/prices
```

## Parameters

| Name                  | Type    | Required | Description                                                                 |
| --------------------- | ------- | -------- | --------------------------------------------------------------------------- |
| `pair`                | string  | Yes      | Forex pair symbol, e.g. `EURUSD`, `GBPUSD`, `USDJPY`                        |
| `interval`            | string  | No       | Candle interval: `minute`, `hour`, `day`, `week`, `month` (default: `hour`) |
| `interval_multiplier` | integer | No       | Multiplier for interval, e.g. `4` for 4-hour candles (default: `1`)         |
| `start_date`          | string  | No       | Start date in ISO 8601 format, e.g. `2024-01-01`                            |
| `end_date`            | string  | No       | End date in ISO 8601 format                                                 |
| `limit`               | integer | No       | Number of candles (default: `100`, max: `5000`)                             |
| `cursor`              | string  | No       | Pagination cursor from `next_page_url`                                      |

## Credit cost

**\$0.005** per request (credits plan only; free for subscription users)

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketdataset.ai/forex/prices?pair=EURUSD&interval=hour&limit=3" \
    -H "X-API-KEY: sk_your_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.marketdataset.ai/forex/prices",
      params={"pair": "EURUSD", "interval": "hour", "limit": 3},
      headers={"X-API-KEY": "sk_your_key"},
  )
  print(response.json())
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "forex_prices": [
    {
      "pair": "EURUSD",
      "interval": "hour",
      "interval_multiplier": 1,
      "open": 1.08421,
      "high": 1.08589,
      "low": 1.08397,
      "close": 1.08534,
      "volume": 12847.0,
      "time": "2024-11-01T15:00:00+00:00"
    }
  ],
  "next_page_url": "https://api.marketdataset.ai/forex/prices?pair=EURUSD&interval=hour&limit=3&cursor=2024-11-01T14:00:00+00:00",
  "meta": {
    "request_id": "req_abc123",
    "credits_used": 0.005,
    "credits_remaining": 49.995
  }
}
```

## Pagination

Results are ordered by `time` descending (newest first). When `next_page_url` is present, use it to fetch the next page:

```python theme={null}
url = "https://api.marketdataset.ai/forex/prices?pair=EURUSD&interval=day&limit=100"
headers = {"X-API-KEY": "sk_your_key"}

all_candles = []
while url:
    data = requests.get(url, headers=headers).json()
    all_candles.extend(data["forex_prices"])
    url = data["next_page_url"]
```