Treasury Management Currency API: FX Hedging & Cash Flow Forecasting for Global Finance

// FX Exposure Calculator using Currency-Exchange.app API
interface FxExposure {
  id: string;
  currency: string;
  amount: number;          // foreign currency amount
  type: 'receivable' | 'payable';
  settlementDate: string;  // ISO date
}

interface HedgeRecommendation {
  exposure: FxExposure;
  baseCurrencyAmount: number;
  unrealizedGainLoss: number;
  hedgeRatio: number;       // 0.0 to 1.0
  hedgeInstrument: 'forward' | 'option';
}

async function calculateFxExposure(
  exposures: FxExposure[],
  baseCurrency: string = 'USD',
  apiKey: string
): Promise<HedgeRecommendation[]> {
  const recommendations: HedgeRecommendation[] = [];

  for (const exposure of exposures) {
    // 1. Fetch live rate from Currency-Exchange.app
    const response = await fetch(
      'https://currency-exchange.app/api/v1/convert',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': apiKey,
        },
        body: JSON.stringify({
          from: exposure.currency,
          to: baseCurrency,
          amount: exposure.amount,
        }),
      }
    );
    const data = await response.json();
    const liveRate = data.rate;
    const baseCurrencyAmount = data.result;

    // 2. Fetch 30-day average rate for comparison
    const avgUrl =
      'https://currency-exchange.app/api/v1/historical'
      + '?base=' + baseCurrency
      + '&quotes=' + exposure.currency
      + '&start=2026-02-12&end=2026-03-14';
    const avgResponse = await fetch(
      avgUrl,
      { headers: { 'x-api-key': apiKey } }
    );
    const avgData = await avgResponse.json();
    const avgRate = calculateAverageRate(avgData.rates);

    // 3. Calculate unrealized P&L
    const unrealizedGainLoss =
      (liveRate - avgRate) * exposure.amount;

    // 4. Determine hedge ratio based on volatility
    const volatility = calculateRateVolatility(avgData.rates);
    const hedgeRatio = volatility > 0.02 ? 0.75 :
                       volatility > 0.01 ? 0.50 : 0.25;

    // 5. Select instrument type
    const hedgeInstrument =
      exposure.amount > 500000 ? 'forward' : 'option';

    recommendations.push({
      exposure,
      baseCurrencyAmount,
      unrealizedGainLoss,
      hedgeRatio,
      hedgeInstrument,
    });
  }

  return recommendations;
}

# Revenue Forecasting with Historical Exchange Rates
import requests
from datetime import datetime, timedelta
from typing import Optional
import numpy as np

class TreasuryForecaster:
    """Multi-scenario revenue forecast using historical FX data."""

    BASE_URL = "https://currency-exchange.app/api/v1"
    SCENARIOS = {
        "bear_case": -0.05,      # 5% adverse move
        "base_case": 0.00,       # no change
        "bull_case": 0.05,       # 5% favorable move
    }

    def __init__(self, api_key: str, base_currency: str = "USD"):
        self.api_key = api_key
        self.base_currency = base_currency
        self.headers = {"x-api-key": api_key}

    def fetch_historical_rates(
        self,
        currency: str,
        days: int = 90
    ) -> list[float]:
        """Fetch 90 days of historical rates for a currency pair."""
        end_date = datetime.utcnow()
        start_date = end_date - timedelta(days=days)

        response = requests.get(
            f"{self.BASE_URL}/historical",
            headers=self.headers,
            params={
                "base": self.base_currency,
                "quotes": currency,
                "start": start_date.strftime("%Y-%m-%d"),
                "end": end_date.strftime("%Y-%m-%d"),
            },
        )
        response.raise_for_status()
        data = response.json()
        return [r["rate"] for r in data["rates"]]

    def forecast_revenue(
        self,
        revenues_by_currency: dict[str, float],
        forecast_period_days: int = 90
    ) -> dict[str, dict]:
        """Generate multi-scenario revenue forecast."""
        forecast = {}

        for currency, amount in revenues_by_currency.items():
            rates = self.fetch_historical_rates(currency)
            current_rate = rates[-1]
            volatility = np.std(
                np.diff(rates) / rates[:-1]
            )

            forecast[currency] = {
                "current_rate": current_rate,
                "volatility_90d": round(float(volatility), 6),
                "scenarios": {},
            }

            for scenario, fx_adjustment in self.SCENARIOS.items():
                adjusted_rate = current_rate * (
                    1 + fx_adjustment
                )
                converted = amount * adjusted_rate
                forecast[currency]["scenarios"][scenario] = {
                    "assumed_rate": round(adjusted_rate, 6),
                    "revenue_in_usd": round(converted, 2),
                    "variance_from_base": round(
                        converted - amount * current_rate, 2
                    ),
                }

        return forecast