> For the complete documentation index, see [llms.txt](https://www.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://www.bluegamma.io/documentation/integrations/api/how-to-guides/fetching-fx-forward-rates.md).

# 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](#multiple-dates-in-one-call)). For the full term structure, use `/fx_forward_curve`.

***

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

**Response:**

```json
{
  "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`           | No       | Future date for the forward rate (ISO 8601 format: `YYYY-MM-DD`). Defaults to today, which returns the spot rate |
| `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](/documentation/data-coverage/data-coverage/supported-fx-currency-pairs.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  |

***

## 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.

```python
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']}")
```

```bash
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:**

```json
{
  "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 (spot plus standard tenors out to 10 years, or forward rates at a regular interval between two dates), use `/fx_forward_curve`. See [Fetching FX Forward Curves](/documentation/integrations/api/how-to-guides/fetching-an-fx-forward-curve.md).

***

## 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-12-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-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`:

```python
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}")
```

```bash
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"
```

***

## 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

```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 == 403:
    print("Access denied - check your API key:", response.json())
elif response.status_code == 404:
    print("Currency pair not supported:", response.json().get("detail"))
elif response.status_code == 422:
    print("Invalid parameters:", response.json().get("detail"))
else:
    print(f"Error {response.status_code}: {response.text}")
```

***

Create a key under **API Keys** in the app sidebar. See [Authentication](/documentation/integrations/api/authentication.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.bluegamma.io/documentation/integrations/api/how-to-guides/fetching-fx-forward-rates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.