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
Related
- Asset hub: Forex
- Symbols: EUR/USD, GBP/USD, USD/JPY, USD/CHF, AUD/USD, USD/CAD
- Docs: API Reference: Forex Rates and Bars, Symbol Formats
- Learn: Forex Trading Sessions and Spread Behaviour