Early access is open. Free sample datasets are live now. Download a sample

Data product · Early access

Currency and FX Pair Reference Data API

Every currency and pair we cover, with ISO codes, full names, quoting precision, how far back the history goes, and whether the FX market is open right now.

Coverage

What you get

Item Detail
Product code FX-REFERENCE
Coverage Every currency and pair in our FX products
Granularity One record per pair
History First available date for daily and intraday data on each pair
Delivery REST and a free CSV download
Update speed Static list, refreshed when we add pairs; market_status live

It's the boring table that makes the rest of the FX API usable. Before you request ten years of USDMXN 1-minute bars, this tells you how many years exist. And before you format a price, it tells you whether the pair quotes to 3 or 5 decimals.

Schema

Schema

Field Type Required Description
symbol string yes Pair, e.g. EURUSD
base_currency string yes ISO 4217 code
quote_currency string yes ISO 4217 code
base_currency_name string yes e.g. Euro
quote_currency_name string yes e.g. US Dollar
display_symbol string optional EUR/USD
decimal_places integer optional Quoting precision
history_start_daily string optional First date of daily history, YYYY-MM-DD
history_start_intraday string optional First date of intraday history
is_active boolean yes Pair currently updated
market_status string optional open or closed now
next_open string optional Next open time, ISO 8601 UTC

Example record (illustrative):

{
  "symbol": "EURUSD",
  "base_currency": "EUR",
  "quote_currency": "USD",
  "base_currency_name": "Euro",
  "quote_currency_name": "US Dollar",
  "display_symbol": "EUR/USD",
  "decimal_places": 5,
  "history_start_daily": "1999-01-04",
  "history_start_intraday": "2010-01-04",
  "is_active": true,
  "market_status": "open",
  "next_open": null
}

Sample data

Sample data

No free pair list file yet; it will be a free CSV once FX products open. A sample file is available on request, and we'll send the current list in this schema.

For real FX data today, the ECB reference rate samples are free to download.

Use cases

Use cases

Validating input. Check user-entered codes against base_currency and quote_currency before calling the rates API. A typo like EUD fails fast instead of returning an empty series.

Formatting prices. Round display prices to decimal_places. JPY pairs usually quote to fewer decimals than EUR/USD, and a checkout page that shows the wrong precision looks broken.

Planning a backtest. Read history_start_intraday for each pair in your basket and start the test at the latest of those dates, so every pair has data from day one.

Weekend handling. Check market_status and next_open before placing orders or alerting. FX closes from Friday evening to Sunday evening New York time, and quotes during that gap are stale.

Code

Code examples

Example: all active pairs.

curl "https://api.marketdata.co/v1/forex/pairs?is_active=true" \
  -H "Authorization: Bearer $MARKETDATA_API_KEY"

Example: Python, find the common intraday start date for a basket.

import os
import requests
import pandas as pd

resp = requests.get(
    "https://api.marketdata.co/v1/forex/pairs",
    headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
)
resp.raise_for_status()
pairs = pd.DataFrame(resp.json()["results"]).set_index("symbol")
basket = ["EURUSD", "GBPUSD", "USDJPY", "AUDUSD"]
start = pd.to_datetime(pairs.loc[basket, "history_start_intraday"]).max()
print("Backtest from", start.date())

Pricing

Pricing

Plan Currency and pair lists
Free, $0 Full access, not counted against your quota
Starter, Pro, Business Same, included

The pair list will also be a free CSV. Almost every provider we studied gives currency lists away, and so do we.

Side by side

How we compare

9 of the 50 providers we studied publish currency or pair lists, and nearly all of them for free. We don't try to charge for it. What we add is useful for code: history start dates per pair and a live market_status, which few free lists include, all keyed on the same symbol you use in our rates, bars and ticks.

FAQ

Frequently asked questions

Which currency codes do you use?

ISO 4217 three-letter codes, such as USD, EUR and JPY. Pairs join two codes with no separator: EURUSD.

Do you include offshore yuan?

Yes, as USDCNH, separate from onshore CNY. They trade at different rates, so we keep them apart.

What time zone is next_open in?

UTC, in ISO 8601. The FX week usually opens Sunday evening New York time, which falls on Sunday evening or Monday morning UTC depending on daylight saving.

Does this call count against my rate limit?

No. Reference lists are planned to sit outside the plan quota, because every other FX call depends on them.

Is market_status real-time?

It reflects the standard FX trading week and holidays as we schedule them. This is not a liquidity measure; spreads can still be wide in the first minutes after the open.

What formats can I get?

JSON from the API and a CSV download.

Keep reading