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.

---

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-06-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-06-15" \
  -H "x-api-key: your_api_key_here"

Response:

{
  "currency_pair": "EURUSD",
  "date": "2026-06-15",
  "rate": 1.1687296324050924
}

Field	Description
currency_pair	The currency pair requested
date	The future date for the forward rate
rate	The forward exchange rate for the specified date

---

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 Available Indices.

---

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

---

Building an FX Forward Curve

To build a complete forward curve, make multiple calls with different dates:

import requests
from datetime import datetime, timedelta

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

# Generate dates for the next 5 years, quarterly
start_date = datetime.now()
dates = [(start_date + timedelta(days=90*i)).strftime("%Y-%m-%d") for i in range(1, 21)]

forward_curve = []
for date in dates:
    params = {
        "currency_pair": "EURUSD",
        "date": date
    }
    response = requests.get(url, headers=headers, params=params)
    if response.status_code == 200:
        forward_curve.append(response.json())

# Now you have a complete forward curve
for point in forward_curve:
    print(f"{point['date']}: {point['rate']}")

# Example for a single date (repeat for each date)
curl -X GET "https://api.bluegamma.io/v1/fx_forward?currency_pair=EURUSD&date=2026-03-15" \
  -H "x-api-key: your_api_key_here"

EURUSD forward curve showing expected exchange rates over time

---

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-06-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-06-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:

import requests

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

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

forecasted_cashflows = []
for date in forecast_dates:
    params = {
        "currency_pair": "EURUSD",
        "date": date
    }
    response = requests.get(url, headers=headers, params=params)
    if response.status_code == 200:
        data = response.json()
        usd_equivalent = eur_revenue_amount * data["rate"]
        forecasted_cashflows.append({
            "date": date,
            "eur_amount": eur_revenue_amount,
            "fx_rate": data["rate"],
            "usd_amount": usd_equivalent
        })

# Print forecast
for cashflow in forecasted_cashflows:
    print(f"{cashflow['date']}: EUR {cashflow['eur_amount']:,.0f} = USD {cashflow['usd_amount']:,.2f} @ {cashflow['fx_rate']}")

# Example for a single forecast date (repeat for each date)
curl -X GET "https://api.bluegamma.io/v1/fx_forward?currency_pair=EURUSD&date=2026-03-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
Multiple forward rates at once	Loop through /fx_forward
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? 📩 [email protected] | 📅 Book a call