> For the complete documentation index, see [llms.txt](https://bluegamma.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluegamma.io/documentation/integrations/api/how-to-guides/fetching-fx-forward-rates.md). # Fetching FX Forward Rates 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 ```python 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"] ``` ```bash 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:** ```json { "currency_pair": "EURUSD", "date": "2026-07-15", "rate": 1.1828578866944446, "spot_rate": 1.17799, "forward_diff": 0.004868, "premium": "0.41%", "days_forward": 91 } ``` | 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 | | `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 | *** ## 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](/documentation/integrations/available-indices.md). *** ## 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 For a full forward curve in a single call, use `/fx_forward_curve`. It returns the spot rate plus standard tenors (1W, 2W, 3W, 1M–12M, 18M, 2Y, 3Y, 5Y, 7Y, 10Y) by default, or forward rates at a custom interval over a date range. ### Standard tenors (default) ```python 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}") ``` ```bash curl -X GET "https://api.bluegamma.io/v1/fx_forward_curve?currency_pair=EURUSD" \ -H "x-api-key: your_api_key_here" ``` **Response:** ```json { "currency_pair": "EURUSD", "spot_rate": 1.17794, "valuation_time": "2026-04-15T10:06:00", "frequency": "standard", "curve": [ { "tenor": "1W", "date": "2026-04-22", "forward_rate": 1.178307, "forward_diff": 0.000367 }, { "tenor": "1M", "date": "2026-05-15", "forward_rate": 1.179635, "forward_diff": 0.001695 }, { "tenor": "3M", "date": "2026-07-14", "forward_rate": 1.182759, "forward_diff": 0.004819 }, { "tenor": "6M", "date": "2026-10-12", "forward_rate": 1.186892, "forward_diff": 0.008952 }, { "tenor": "1Y", "date": "2027-04-15", "forward_rate": 1.19383, "forward_diff": 0.01589 }, { "tenor": "2Y", "date": "2028-04-15", "forward_rate": 1.20569, "forward_diff": 0.02775 }, { "tenor": "5Y", "date": "2031-04-15", "forward_rate": 1.24021, "forward_diff": 0.06227 }, { "tenor": "10Y", "date": "2036-04-15", "forward_rate": 1.30418, "forward_diff": 0.12624 } ] } ``` ### 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. ```bash curl -X GET "https://api.bluegamma.io/v1/fx_forward_curve?currency_pair=EURUSD&frequency=3M&start_date=2026-04-15&end_date=2031-04-15" \ -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` instead If you only need a forward rate at a **single arbitrary date** (e.g. matching a specific cash flow), call `/fx_forward` directly rather than the curve endpoint. Use `/fx_forward_curve` whenever you want the full term structure. *** ## Reproducibility with `valuation_time` For reproducible valuations, use `valuation_time` to lock in the market state at a specific point in time: ```python 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) ``` ```bash 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: ```python 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']}") ``` ```bash # 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" ``` {% hint style="success" %} **Need FX forward data for your treasury models?** Get an API key and start pulling live rates. [Book a demo →](https://app.lemcal.com/@alivohra/website-demo?back=1) {% endhint %} *** ## Related Endpoints | If you need... | Use | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Current spot rate | [`/fx`](/documentation/integrations/api/api-reference.md) | | A full forward curve | [`/fx_forward_curve`](/documentation/integrations/api/api-reference.md) — spot + standard tenors (or a custom frequency) in a single call | | Interest rate forwards | [`/forward_rate`](/documentation/integrations/api/how-to-guides/getting-forward-rates.md) | *** ## Error Handling ```python 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?**\ 📩 | 📅 [Book a call](https://app.lemcal.com/@alivohra/website-demo?back=1) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bluegamma.io/documentation/integrations/api/how-to-guides/fetching-fx-forward-rates.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.