# Forex API

> Live exchange rates and daily history for major and cross currency pairs, from EUR/USD to USD/JPY, over the same API key and endpoints as stocks and crypto.

Canonical page: https://stockdataapi.com/forex-api

- Symbol format: `EURUSD=X`: the base and quote currency codes, then `=X`
- Trading hours: Sunday evening to Friday 17:00, New York time
- Quote freshness: About a minute while the market is open
- Daily history: `EURUSD=X` from December 2003, `USDJPY=X` from 1996
- Volume: Not reported: always 0 for currency pairs

## Symbol format

Write the base currency's code, then the quote currency's, then `=X`: `EURUSD=X` is the price of one euro in US dollars. A single code with `=X` is that currency against the dollar, so `JPY=X` is the same pair as `USDJPY=X`. In a URL, encode `=` as `%3D`.

| Symbol | What it is |
| --- | --- |
| `EURUSD=X` | Euro in US dollars |
| `GBPUSD=X` | British pound in US dollars |
| `USDJPY=X` | US dollar in Japanese yen |
| `JPY=X` | The same pair as USDJPY=X |
| `EURJPY=X` | Euro in yen, a cross |
| `DX-Y.NYB` | US Dollar Index (ICE) |

## Endpoints

- [Quote API](https://stockdataapi.com/docs/quote.md), `GET /v6/finance/quote`: Rate, change, bid and ask for a batch of pairs, alongside stocks or crypto in the same call if you like.
- [Chart API: OHLCV history](https://stockdataapi.com/docs/chart.md), `GET /v8/finance/chart/{symbol}`: Daily, weekly and monthly history plus intraday bars. Volume is always 0.
- [Spark API: close-price series](https://stockdataapi.com/docs/spark.md), `GET /v8/finance/spark`: Close-only series for a rates board.
- [Market summary API](https://stockdataapi.com/docs/market-summary.md), `GET /v6/finance/quote/marketSummary`: Major currency tiles in the market overview, alongside indices and futures.

## Example request

```bash
curl -H "x-api-key: $KEY" "https://api.stockdataapi.com/v6/finance/quote?symbols=EURUSD%3DX,GBPUSD%3DX,USDJPY%3DX"
```

## Example response

```json
{
  "quoteResponse": {
    "result": [
      {
        "symbol": "EURUSD=X",
        "shortName": "EUR/USD",
        "quoteType": "CURRENCY",
        "currency": "USD",
        "marketState": "REGULAR",
        "regularMarketPrice": 1.1209,
        "regularMarketChangePercent": -0.4259,
        "bid": 1.1208,
        "ask": 1.1211,
        "regularMarketVolume": 0,
        "exchangeTimezoneName": "Europe/London"
      }
    ],
    "error": null
  }
}
```

## Good to know

- The source reports no volume for currency pairs, so `regularMarketVolume` and chart volumes are 0.
- Outside trading hours a quote's `marketState` reads `CLOSED`, and the last rate stands until the market reopens.
- There is no conversion endpoint: to convert an amount, multiply it by the pair's `regularMarketPrice`.
- `DX-Y.NYB`, the US Dollar Index, is an index rather than a pair, so it has no `=X`.

## Questions

### Which currency pairs are available?

Majors, minors and crosses the source quotes, such as `EURUSD=X`, `GBPUSD=X`, `USDJPY=X` and `EURJPY=X`, plus the US Dollar Index (`DX-Y.NYB`). A pair nobody has asked for before is fetched on the first request.

### When is the forex market open?

From Sunday evening to Friday at 17:00 New York time. Outside those hours a quote reads `CLOSED` and keeps the last rate until the market reopens.

### Does the API report forex volume?

No. The source reports no volume for currency pairs, so volume fields are 0.

### How far back does exchange-rate history go?

Daily history starts in December 2003 for EUR/USD and in 1996 for USD/JPY, with intraday bars for recent weeks.

### Can the API convert between currencies?

There is no conversion endpoint. Multiply the amount by the pair's `regularMarketPrice`: 100 euros at a `EURUSD=X` rate of 1.12 is 112 US dollars.