Fetching FX Forward Rates

Use the /fx_forward endpoint to get forward exchange rates for any supported currency pair, enabling FX hedging, cash flow forecasting, and valuation models.

The /fx_forward endpoint returns the forward exchange rate for a specific currency pair and future date. Use this for hedging foreign currency exposure, forecasting cash flows, or building financial models that require future FX rates.

For a list of specific dates in one request, use /fx_forwards (see Multiple Dates in One Call). For the full term structure, use /fx_forward_curve.

---

Basic Example

import requests

url = "https://api.bluegamma.io/v1/fx_forward"
headers = {"x-api-key": "your_api_key"}

params = {
    "currency_pair": "EURUSD",
    "date": "2026-12-15"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
forward_rate = data["rate"]

curl -X GET "https://api.bluegamma.io/v1/fx_forward?currency_pair=EURUSD&date=2026-12-15" \
  -H "x-api-key: your_api_key_here"

Response:

{
  "currency_pair": "EURUSD",
  "date": "2026-12-15",
  "valuation_time": null,
  "rate": 1.1505346706554784,
  "spot_rate": 1.14636,
  "forward_diff": 0.004175,
  "premium": "0.36%",
  "days_forward": 88,
  "extrapolated": false
}

Field	Description
currency_pair	The currency pair requested
date	The future date for the forward rate
valuation_time	The snapshot the rate was priced off (null for the latest data)
rate	The forward exchange rate for the specified date
spot_rate	The spot rate at the valuation time, for reference
forward_diff	Absolute difference between the forward rate and spot
premium	Forward premium as a percentage of spot
days_forward	Calendar days between the valuation date and the forward date
extrapolated	true when the date lies beyond the pair's last quoted tenor

---

Parameters

Parameter	Required	Description
currency_pair	Yes	Currency pair in ISO format (e.g., EURUSD, GBPUSD, USDJPY)
date	Yes	Future date for the forward rate (ISO 8601 format: YYYY-MM-DD)
valuation_time	No	Historical timestamp (ISO 8601) for reproducibility

---

Currency Pair Format

Currency pairs follow the ISO standard format:

• Base currency (first 3 letters) + Quote currency (last 3 letters)
• Example: EURUSD means EUR is the base, USD is the quote
• The forward rate represents how many units of quote currency equal 1 unit of base currency

Common Currency Pairs:

• EURUSD - Euro to US Dollar
• GBPUSD - British Pound to US Dollar
• USDJPY - US Dollar to Japanese Yen
• AUDUSD - Australian Dollar to US Dollar
• USDCAD - US Dollar to Canadian Dollar
• EURGBP - Euro to British Pound

For the full list of supported currency pairs, see Supported FX Currency Pairs.

---

When to Use FX Forward Rates

Use Case	Example
FX hedging	Lock in forward rates for foreign currency debt service payments
Cash flow forecasting	Project future revenue or expenses in different currencies
Valuation models	Discount foreign currency cash flows back to home currency
Risk management	Assess FX exposure across a portfolio of foreign assets
Financial planning	Model capital expenditures or investments in foreign currencies

---

Multiple Dates in One Call

The /fx_forwards endpoint returns forward rates for an explicit list of value dates in a single request, all priced off one curve snapshot. This is the most efficient way to price a set of specific dates, for example a schedule of payment or settlement dates, in one request rather than one call per date.

import requests

url = "https://api.bluegamma.io/v1/fx_forwards"
headers = {"x-api-key": "your_api_key"}

params = {
    "currency_pair": "EURUSD",
    "dates": ["2026-12-31", "2027-06-30", "2027-12-31"],
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
for point in data["rates"]:
    print(f"{point['date']}  {point['rate']:.6f}  premium={point['premium']}")

curl -X GET "https://api.bluegamma.io/v1/fx_forwards?currency_pair=EURUSD&dates=2026-12-31&dates=2027-06-30&dates=2027-12-31" \
  -H "x-api-key: your_api_key_here"

Response:

{
  "currency_pair": "EURUSD",
  "dates": ["2026-12-31", "2027-06-30", "2027-12-31"],
  "valuation_time": null,
  "spot_rate": 1.14618,
  "rates": [
    { "date": "2026-12-31", "rate": 1.1511457681867285, "forward_diff": 0.004966, "premium": "0.43%", "days_forward": 104, "extrapolated": false },
    { "date": "2027-06-30", "rate": 1.159420409673611,  "forward_diff": 0.01324,  "premium": "1.16%", "days_forward": 285, "extrapolated": false },
    { "date": "2027-12-31", "rate": 1.167428175981006,  "forward_diff": 0.021248, "premium": "1.85%", "days_forward": 469, "extrapolated": false }
  ],
  "timestamp": "2026-09-18T15:53:57"
}

Each entry in rates carries the same fields as /fx_forward, plus extrapolated, which is true when the date lies beyond the pair's last quoted tenor. valuation_time is null when you request the latest data, and timestamp is the snapshot the whole set was priced off.

Parameters

Parameter	Required	Description
currency_pair	Yes	Currency pair in ISO format (e.g., EURUSD)
dates	Yes	List of value dates (ISO 8601 YYYY-MM-DD), up to 500, in any order

Notes

• All dates are priced off a single curve snapshot, so the values are mutually consistent.
• A value date on or before the snapshot returns the spot rate.
• Prefer this over repeated /fx_forward calls whenever you need a set of specific dates, such as monthly payment dates.

---

Building an FX Forward Curve

For a full forward curve in a single call, use /fx_forward_curve. It returns the spot rate plus standard tenor points out to 10 years (weekly to 3 weeks, monthly to 1 year, then annual points), or forward rates at a custom interval over a date range. The exact set of standard tenors depends on the market data available for the pair.

Standard tenors (default)

import requests

url = "https://api.bluegamma.io/v1/fx_forward_curve"
headers = {"x-api-key": "your_api_key"}

response = requests.get(url, headers=headers, params={"currency_pair": "EURUSD"})
data = response.json()

print(f"Spot: {data['spot_rate']}")
for point in data["curve"]:
    print(f"{point['tenor']:>4}  {point['date']}  {point['forward_rate']:.6f}  diff={point['forward_diff']:+.6f}")

curl -X GET "https://api.bluegamma.io/v1/fx_forward_curve?currency_pair=EURUSD" \
  -H "x-api-key: your_api_key_here"

Response (abbreviated to a few tenors):

{
  "currency_pair": "EURUSD",
  "spot_rate": 1.14619,
  "valuation_time": "2026-09-18T15:53:59",
  "frequency": "standard",
  "curve": [
    { "tenor": "1W",  "date": "2026-09-25", "forward_rate": 1.146464, "forward_diff": 0.000274, "extrapolated": false },
    { "tenor": "1M",  "date": "2026-10-18", "forward_rate": 1.147549, "forward_diff": 0.001359, "extrapolated": false },
    { "tenor": "3M",  "date": "2026-12-17", "forward_rate": 1.150459, "forward_diff": 0.004269, "extrapolated": false },
    { "tenor": "6M",  "date": "2027-03-17", "forward_rate": 1.154652, "forward_diff": 0.008462, "extrapolated": false },
    { "tenor": "1Y",  "date": "2027-09-18", "forward_rate": 1.162845, "forward_diff": 0.016655, "extrapolated": false },
    { "tenor": "2Y",  "date": "2028-09-17", "forward_rate": 1.178901, "forward_diff": 0.032711, "extrapolated": false },
    { "tenor": "5Y",  "date": "2031-09-17", "forward_rate": 1.226061, "forward_diff": 0.079871, "extrapolated": false },
    { "tenor": "10Y", "date": "2036-09-15", "forward_rate": 1.305862, "forward_diff": 0.159672, "extrapolated": false }
  ]
}

Custom frequency

Pass any tenor-style interval (1D, 1W, 1M, 3M, 6M, 12M) along with a start_date and end_date to get forward rates at that cadence.

curl -X GET "https://api.bluegamma.io/v1/fx_forward_curve?currency_pair=EURUSD&frequency=3M&start_date=2026-09-18&end_date=2031-09-18" \
  -H "x-api-key: your_api_key_here"

Parameters

Parameter	Required	Description
currency_pair	Yes	Currency pair in ISO format (e.g., EURUSD)
frequency	No	standard (default) for standard tenors, or an interval like 1D, 1W, 1M, 3M
start_date	No	Start of the date range for custom frequency (ignored when frequency=standard)
end_date	No	End of the date range for custom frequency (ignored when frequency=standard)

EURUSD forward curve: spot plus standard tenors

When to use /fx_forward or /fx_forwards instead

If you only need a forward rate at a single arbitrary date (e.g. matching a specific cash flow), call /fx_forward directly. For a set of specific dates that are not standard tenors, use /fx_forwards. Use /fx_forward_curve whenever you want the full term structure or a regular interval.

---

Reproducibility with valuation_time

For reproducible valuations, use valuation_time to lock in the market state at a specific point in time:

params = {
    "currency_pair": "EURUSD",
    "date": "2026-12-15",
    "valuation_time": "2025-12-31T16:00:00Z"  # ISO 8601 format
}

response = requests.get(url, headers=headers, params=params)

curl -X GET "https://api.bluegamma.io/v1/fx_forward?currency_pair=EURUSD&date=2026-12-15&valuation_time=2025-12-31T16%3A00%3A00Z" \
  -H "x-api-key: your_api_key_here"

Without valuation_time, you get the latest data. With it, you get the forward rate exactly as it was at that timestamp—essential for reproducing valuations months later or for audit trails.

---

Practical Example: Cash Flow Forecasting

If you have revenue or expenses in EUR but report in USD, you can forecast the USD equivalent using forward rates. The whole schedule can be priced in a single call with /fx_forwards:

import requests

url = "https://api.bluegamma.io/v1/fx_forwards"
headers = {"x-api-key": "your_api_key"}

# Future revenue/expense dates (quarterly forecast)
forecast_dates = ["2027-03-31", "2027-06-30", "2027-09-30", "2027-12-31"]
eur_revenue_amount = 1_000_000  # EUR 1M per quarter in foreign revenue

response = requests.get(
    url,
    headers=headers,
    params={"currency_pair": "EURUSD", "dates": forecast_dates},
)
data = response.json()

for point in data["rates"]:
    usd_equivalent = eur_revenue_amount * point["rate"]
    print(f"{point['date']}: EUR {eur_revenue_amount:,.0f} = USD {usd_equivalent:,.2f} @ {point['rate']:.6f}")

curl -X GET "https://api.bluegamma.io/v1/fx_forwards?currency_pair=EURUSD&dates=2027-03-31&dates=2027-06-30&dates=2027-09-30&dates=2027-12-31" \
  -H "x-api-key: your_api_key_here"

Need FX forward data for your treasury models? Get an API key and start pulling live rates. Book a demo →

---

Related Endpoints

If you need...	Use
Current spot rate	/fx
Forwards for several specific dates	/fx_forwards — an explicit list of value dates in one call
A full forward curve	/fx_forward_curve — spot + standard tenors (or a custom frequency) in a single call
Interest rate forwards	/forward_rate

---

Error Handling

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print(f"Forward rate: {data['rate']}")
elif response.status_code == 400:
    print("Invalid parameters:", response.json().get("message"))
elif response.status_code == 401:
    print("Authentication failed - check your API key")
elif response.status_code == 404:
    print("Currency pair not supported or date out of range")
else:
    print(f"Error {response.status_code}: {response.text}")

---

Need an API key? 📩 [e-mail] | 📅 Book a call