Blame for README.md

---
title: FXShield
emoji: 💱
colorFrom: blue
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: FX exposure and hedging simulator.
---

# FXShield

### Currency Risk Intelligence Studio | Hugdrigo Project 097

**FXShield** is a self-contained educational tool for currency exposure management. It helps explain how receivables, payables, manually entered FX rates, and simple forward hedges affect the modeled USD cash settlement of a hypothetical international portfolio.

**Short description:** FX exposure and hedging simulator.

## Launch on Hugging Face

1. Create a new **Space** at <https://huggingface.co/new-space>.
2. Set **Owner:** `Hugdrigo` and **Space name:** `fxshield-currency-risk-studio`.
3. Choose **Static** SDK, a blank template, **Public**, and **MIT**.
4. Upload `README.md`, `index.html`, and `LICENSE` directly to the root of the Space. Do not put them inside a subfolder or upload the ZIP as a single file.
5. Open the Space and confirm that the Command Center, Scenario Lab, Exposure Ledger, FX Assumptions, and Methodology screens load.

For local testing, open `index.html` in a modern desktop or mobile browser that permits local files, or serve the folder from a local static web server. There are no installation steps, build commands, API keys, CDN dependencies, backends, or GPU requirements.

## Capabilities

- Executive dashboard with gross notional FX exposure, weighted hedge coverage, gross sensitivity to an adverse 10% move, and currency concentration.
- Original-currency receivables and payables, editable with counterparty, settlement horizon, and hedge coverage. Existing records can be archived or restored without deletion.
- Six editable currency pairs quoted as **USD per one foreign-currency unit**: EUR, GBP, JPY, BRL, CAD, and MXN. Spot and forward rates are entirely user-provided; the default values are synthetic examples.
- Four ready-to-use scenario presets: base case, USD strengthens, USD weakens, and individually adverse movements. Stress magnitude is configurable from 0% to 30%.
- Comparison of hedged versus unhedged settlement values and a deterministic sensitivity chart from -20% to +20%.
- An illustrative, reproducible 500-draw uncertainty simulation (5th, median, and 95th percentiles).
- CSV exports, portable JSON backups/restoration, local browser persistence where supported, and responsive light/dark interface.

## Calculation methodology

For each active exposure, define:

- `s = +1` for a receivable and `s = -1` for a payable.
- `A` = notional amount in the foreign currency.
- `h` = share notionally forward-hedged, ranging from `0` to `1`.
- `F` = user-supplied forward USD rate per foreign-currency unit.
- `S_scenario` = user-supplied spot USD rate adjusted by the scenario shock.

Then:

```
modeled_cash_settlement_USD = s * A * (h * F + (1 - h) * S_scenario)
```

In the dashboard, **gross USD exposure** is the sum of `A × spot` for all active positions, with receivable/payable direction ignored. The **weighted hedge coverage** is total `A × spot × h` divided by total `A × spot`. The **10% gross adverse sensitivity bound** is `10% × sum(A × spot × (1 - h))`, deliberately ignoring natural offsets and netting. It is not a probability, Value at Risk, or a modeled account balance.

The **uniform stress** multiplies all spot quotes by `1 ± shock`. The **individual adverse stress** reduces the spot rate on each receivable and increases it on each payable. This is a deliberately conservative synthetic construct, not one coherent macroeconomic scenario.

The **500-draw sampler** uses a fixed pseudo-random seed, a shared Gaussian stress factor with assumed standard deviation 7.5%, and independent currency-specific Gaussian components with assumed standard deviation 5%; aggregate shock factors are limited to ±40%. These choices are *illustrative* and **not estimated from historical markets**. Percentiles are not calibrated risk probabilities.

## Privacy, safety, and data quality

- **No live market rates** or brokerage/trading integration. The app never places real trades.
- All startup organizations, original amounts, currency rates, and instruments are synthetic.
- The model does not include options, cross-currency swaps, mark-to-market valuation, interest-rate curves, tenor-specific forward pricing, tax, margin, basis risk, hedge accounting, credit risk, bid/ask spreads, market liquidity, or actual contracts.
- No external network requests or third-party resources are included. Data stays in the browser unless a user explicitly exports a file.
- Imported JSON must match the FXShield v1 schema and pass field, currency, range, and uniqueness validation; imports are limited to 250 KB and 300 exposure records. Imports require confirmation before replacement.
- User-supplied text is escaped when added to the interface; CSV cells that could be interpreted as spreadsheet formulas are prefixed for protection.
- This is **a scenario demonstration, not financial, investment, accounting, or treasury advice**. Have a qualified professional review real decisions.

## Verification performed

- Syntax-checked the JavaScript with Node.js.
- Performed 40 functional/browser checks covering navigation, CRUD, archive/restore, scenarios, backup export/import, validation, safety handling, theme switching, and eight screen widths (320–1440 px).
- Performed 14,003 additional mathematical and deterministic checks of the engine against independent formulas.
- Captured desktop, mobile, dark theme, and scenario previews outside the three-file deployment bundle.

These are local tests; the published Hugging Face Space must be verified separately after upload. Results do not establish real-world statistical calibration or trading suitability.

## Project files

```text
FXShield_Project_97/
├── README.md     # Space configuration and documentation
├── index.html    # Application, styling, and JavaScript
└── LICENSE       # MIT license
```

**Creator:** Hugdrigo portfolio, Project 097. **License:** MIT.