PythonRust

The API is under testing and may change before release.

How FX products work

Every FX product here comes back to one idea: two currencies, each with its own discount curve, and a spot rate that ties them together today. This page explains how forwards, swaps and options follow from that, how an FX desk quotes volatility, and what changes when one currency can't be delivered offshore. The reference pages list the calls; this page is the why behind them.

What every FX product shares

An FX rate is quoted as units of the quote currency per one unit of the base: EUR/USD at 1.10 means 1.10 dollars per euro. A forward is quoted the same way, either as an outright rate or as forward points, the outright less the spot, usually in pips (units of the fourth decimal).

A market for FX products holds three things: a discount curve for each currency, built from that currency's own quotes, and the spot that converts between them, set with with_fx_rates. Which pairs exist, their spot lags and their calendars are market conventions, listed in the FX conventions catalog.

Covered interest parity

A euro held to a date $T$ and exchanged then must cost the same, in dollars, as a euro exchanged now with the dollars held to $T$ . Otherwise you could borrow in one currency, lend in the other and lock in a profit. Writing $S$ for the spot and $P_{\text{EUR}}$ , $P_{\text{USD}}$ for the two discount factors to $T$ , the forward is

F(T) = S \, \frac{P_{\text{EUR}}(T)}{P_{\text{USD}}(T)}.

When dollar rates are above euro rates, $P_{\text{USD}} < P_{\text{EUR}}$ , and the euro trades at a forward premium.

FX forwards

A forward buying $N$ euros at contract rate $K$ on $T$ receives $N$ euros and pays $NK$ dollars. Convert the euros at the forward and discount in dollars, and its value is

V = N\,(F(T) - K)\,P_{\text{USD}}(T).

Struck at $K = F(T)$ it's worth nothing. Once $T$ has passed the currencies have been exchanged, and the contract is worth nothing too. See FX forwards.

FX swaps

An FX swap exchanges two currencies now and exchanges them back later, at rates agreed today. The second exchange undoes the first, so it carries no currency risk: it's a loan in one currency secured by the other. That's why banks use it to fund in a currency they don't hold.

It's two forwards on one pair with opposite notionals: buy $N$ base on $T_1$ at $K_1$ , sell $N$ base on $T_2$ at $K_2$ . Its value is the sum of the two forwards' values,

V = N\,(F(T_1) - K_1)\,P_{\text{quote}}(T_1) \;-\; N\,(F(T_2) - K_2)\,P_{\text{quote}}(T_2).

The swap points are $F(T_2) - F(T_1)$ , the interest rate differential over the swap's life. Because the points carry that differential, FX swaps are also the instruments that mark one currency's discount curve against another's, which cross-currency calibration does. See FX swaps.

FX options

An FX option is the right, not the obligation, to exchange two currencies at a fixed rate on a future date. It expires on one date and, if exercised, delivers on its own delivery date, usually the pair's spot lag after expiry.

How the surface is quoted

An FX desk doesn't quote vols by strike. For each expiry it quotes three numbers:

the at-the-money vol;
the 25-delta risk reversal, the call's vol less the put's, which carries the skew;
the 25-delta butterfly, the wings' average vol over the at-the-money vol, which carries the smile's curvature.

From those three, each expiry's smile is built as three nodes keyed by the option they price: 25P, the put with delta $-0.25$ ; ATM, the delta-neutral straddle; and 25C, the call with delta $+0.25$ . An option reads its vol at its strike, with each node placed at the strike its delta names. Across expiries the surface is linear in total variance. How a pair's deltas are quoted, spot or forward, premium-adjusted or not, is a market convention you pass when you build the surface; see FX vol surface.

Garman-Kohlhagen

Under Garman-Kohlhagen the base currency pays a continuous yield, its own interest rate. With $F$ the forward to delivery, $\sigma$ the vol the smile reads at the strike $K$ , $\tau$ the time to expiry and $P_{\text{quote}}$ the quote currency's discount factor to delivery, a call on $N$ units of base is worth

C = N\,P_{\text{quote}}\,\big[F\,\Phi(d_1) - K\,\Phi(d_2)\big], \qquad d_{1,2} = \frac{\ln(F/K) \pm \tfrac12 \sigma^2 \tau}{\sigma\sqrt{\tau}},

and a put is $P = N\,P_{\text{quote}}\,[K\,\Phi(-d_2) - F\,\Phi(-d_1)]$ .

Put-call parity

A call less a put at one strike pays $N(X_T - K)$ whatever the rate $X_T$ at expiry: that's a forward bought at $K$ . So, whatever the vol,

C - P = N\,(F - K)\,P_{\text{quote}}.

Strikes named by delta

A strike can be named by its delta instead. Under the spot convention a put's delta is $-P_{\text{base}}\,\Phi(-d_1)$ , so the 25-delta put is the strike where that equals $-0.25$ , with $d_1$ worked out at the vol the smile reads at that strike. The strike and the vol depend on each other, so the pair is solved together. On a smile that quotes the 25-delta put, the answer is the 25P node: its strike and its vol. See FX options.

Non-deliverable forwards

Some currencies, such as the won, the rupee and the real, can't be delivered offshore. A non-deliverable forward (NDF) never exchanges the local currency. Two business days before its value date, the pair's published rate, the fixing, is compared with the contract rate, and the difference on the notional is paid in a deliverable currency, usually dollars.

Because the local currency can't leave the country, the forward traded offshore isn't the one onshore rates imply. Capital controls keep the two markets apart, and the gap moves with demand for offshore hedging. The offshore forward lives on the offshore curve: the local currency's discount under dollar collateral, KRW-CSA-USD for won, which the offshore recipe marks from NDF outrights:

P^{\text{off}}_{\text{KRW}}(T) = \frac{S}{F^{\text{off}}(T)}\,P_{\text{USD}}(T).

An NDF buying $N$ dollars against won at contract rate $K$ pays $N(1 - K/X)$ dollars at the fixing $X$ . Before the fixing, that amount is projected at the offshore forward and discounted in dollars, since dollars are what it pays:

V = N\left(1 - \frac{K}{F^{\text{off}}(T)}\right) P_{\text{USD}}(T).

The recipe marks the offshore curve so that $F^{\text{off}}$ reproduces each quoted outright, so an NDF struck at a quoted outright is worth nothing. The onshore forward is a different number, and the NDF doesn't read it. Each market's NDF terms, its fixing source, calendars and lags, are carried as templates, listed in the non-deliverable conventions catalog. See NDF.

Non-deliverable options

A non-deliverable option (NDO) is to an FX option what an NDF is to a forward. It's European, it expires on the fixing date the NDF terms give for its tenor, and its payoff is converted at that fixing and paid in dollars. Converting at the fixing doesn't change the payoff's shape, so it's priced by Garman-Kohlhagen on the pair's surface. What changes is the forward: the won leg is never paid, so the option reads the offshore forward, as the NDF does.

A call less a put at one strike pays $N(X - K)$ won, converted at the fixing to dollars, which is the NDF at that strike:

C_{\text{NDO}} - P_{\text{NDO}} = V_{\text{NDF}}(K).

See NDO.

Non-deliverable swaps

A non-deliverable swap (NDS) is the local market's own interest rate swap, a won swap on the 3M CD rate for example, with each net payment converted at the FX fixing two business days before it and paid in dollars. A non-deliverable cross-currency swap (NDCCS) pays a local fixed leg, settled in dollars at each payment's fixing, against a SOFR leg, and exchanges notionals at the end.

Both read the offshore curve. NDS par rates don't mark it, because all of an NDS's payments convert by the same factor and say little about the discount. What they do mark is the local index the swap floats on: the KRW recipe takes KRW-CD-NDS par rates, when the sheet quotes them, and marks the 3M CD projection from them. Each of those rungs is an NDS solved against the dollar curve and the offshore won curve, so those two must be on the market before the KRW sheet is added. An NDS's par rate is the fixed rate at which it's worth nothing; an NDCCS's is the local fixed rate at which its converted local leg equals its SOFR leg. See NDS and NDCCS.

From formula to API

Symbol	Meaning	Rust	Python
$S$	the spot, quote per base	`MarketContext::with_fx_rates`	`MarketContext.with_fx_rates`
$P_{\text{EUR}}, P_{\text{USD}}$	each currency's discount	`with_recipe_quotes` per currency	`with_recipe_quotes` per currency
$F(T)$	the forward	$S\,P_{\text{base}}/P_{\text{quote}}$ from the market's curves	$S\,P_{\text{base}}/P_{\text{quote}}$ from the market's curves
$V$ of a forward	its value	`FxForward::new`, then `AnyInstrument::npv`	`products.fx_forward`, then `Instrument.npv`
an FX swap	two forwards as one trade	`FxSwap::new(near, far)`	`products.fx_swap(near, far)`
$\sigma(K, T)$	the pair's surface	`FxVolSurface::new`, pinned by `with_fx_vols`	`vols.FxVolSurface`, pinned by `with_fx_vols`
$C, P$	an option's value	`FxOption::new`, then `AnyInstrument::npv`	`products.fx_option`, then `Instrument.npv`
a strike by delta	the 25-delta put	`Strike::AtDelta(0.25)`	`products.fx_option(…, delta=0.25)`
$P^{\text{off}}_{\text{KRW}}$	the offshore curve	`with_recipe_quotes` under `KRW-CSA-USD`	`with_recipe_quotes("KRW-CSA-USD", …)`
an NDF, an NDO	drafted from a template	`AnyTemplate::ndf`, `AnyTemplate::ndo`	`Template.ndf`, `Template.ndo`
an NDS, an NDCCS	drafted from a template	`AnyTemplate::nds`, `CrossCurrencySwap::from_template`	`Template.nds`, `Template.cross_currency_swap`