derivatives pricing

# valoswiss-derivatives-pricing (32°)

**Macro-categoria**: 📈 QUANT/MARKETS (sub-categoria QUANT-INTELLIGENCE bridge)
**Scope**: Pricing engine derivati vanilla + exotic + structured + IR derivatives, Greeks, vol surface, hedging overlay, stress test scenarios
**Born**: 2026-05-03 V20 (sidecar planning + monorepo skeleton in commit window)
**Owner downstream**: ADVISOR (proposta hedging overlay propri portfolios) · RELATIONSHIP_MANAGER (idem) · SUPERVISOR/ADMIN (cross-tenant + structured product creation + vol surface upload)
**Last aligned**: 2026-05-03 V20

> **PROTOTYPE-PHASE caveat**: questo agente opera in fase prototipo. La normativa applicabile (MIFID II complex products, suitability test ESMA Q&A 2014, KID PRIIPs reg. 1286/2014, art. 50 CdR ex-ante stress) è trattata come **signal target post-prototipo**, NON come hard gate bloccante. La R-Audit gate è MAJOR (peso 8). Capability over compliance: si può mergere con remarks se la business logic regge. Compliance hardening è esplicito milestone V21+ (KID auto-generation V22+). I derivati sono "complex products" MIFID II — il cliente NON vede mai pricing/Greeks dirette: solo l'advisor riceve raccomandazione hedging overlay.

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Sidecar Python derivatives health**
   ```bash
   curl -s http://127.0.0.1:8893/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","engines":{"quantlib":"1.34","tfquantfinance":"0.0.1.dev38","pyderivatives":"0.5.x"}}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep derivatives-py`.
3. **Sidecar parallel portfolio-opt e trading-agents (per overlay coord)**
   ```bash
   curl -s http://127.0.0.1:8892/healthz | jq .   # portfolio-opt :8892
   curl -s http://127.0.0.1:8890/healthz | jq .   # trading-agents :8890
   ```
   Non bloccanti — se down, l'agente lavora ugualmente ma senza coordination overlay.
4. **NestJS proxy health (futuro modulo)**
   ```bash
   curl -s http://127.0.0.1:4010/api/derivatives/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, circuitBreaker:{state:'closed'} }`. In V20 questo endpoint potrebbe non esistere ancora — annotare nel handoff.
5. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le model `DerivativePricing` / `VolatilitySurface` / `HedgingStrategy` / `StructuredProduct` siano applicate (post-W3).
6. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"derivatives": true` subito dopo `portfolioOptimization` (3-Point Registration V16).
7. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'derivatives'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER`. **NON** in CLIENT-facing packs (PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL) — i derivati sono complex products MIFID II, l'advisor ne propone hedging overlay, il cliente firma post-suitability test (V21+).
8. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `derivatives` con `sidebarSection: 'OPERARE'`, `requiredRole: 'ADVISOR'`, `personaHint: 'predictive'`, icon `📈`.
9. **R-Audit gate (MAJOR, peso 8)**: prima di qualsiasi commit su file CRITICAL (vedi §3 R-Audit gates), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic --weight major`. In prototype-phase il verdict NEEDS-CHANGES è merge-able con remarks documentati nel commit body, MA mai con CRITICAL findings business-logic.

Se uno qualunque dei 8 punti operativi (1-8) fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Pricing engines supportati

| Engine | Repo riferimento | Use case primario | Modello |
|---|---|---|---|
| **Black-Scholes-Merton** | QuantLib `AnalyticEuropeanEngine` | European vanilla call/put | closed-form GBM con dividend yield |
| **Binomial CRR/JR** | QuantLib `BinomialVanillaEngine` | American option early exercise | Cox-Ross-Rubinstein o Jarrow-Rudd N=1000 step |
| **Finite Difference** | QuantLib `FdBlackScholesVanillaEngine` | American + barrier option | Crank-Nicolson grid 100×100 |
| **Monte Carlo Heston** | QuantLib `MCHestonHullWhiteEngine` | Exotic + stochastic vol | Heston SDE + Hull-White rates Euler-Milstein |
| **Heston semi-analytic** | QuantLib `AnalyticHestonEngine` | European under stochastic vol | characteristic function FFT |
| **Bates jump-diffusion** | PyDerivatives `BatesEngine` | jump risk pricing | Heston + Merton-Kou jump component |
| **SABR** | QuantLib `SabrInterpolatedSmileSection` | vol surface fit IR + equity | α, β, ρ, ν calibration on market quotes |
| **SVI** | custom (Gatheral 2004) | equity vol surface arb-free | raw/natural/jw parametrization |
| **G2++ / Hull-White** | QuantLib `G2SwaptionEngine` | swaption + Bermudan | 2-factor Gaussian short-rate |
| **TensorFlow GPU** | google/tf-quant-finance | batch pricing 1000+ contracts | Black-Scholes vectorized GPU |
| **Quantra Rust** | wojkar/quantra | high-perf real-time | gRPC + REST, sub-ms latency |

### 1.2 Product taxonomy supportata

```
Vanilla
├─ European          (BS analytic, AnalyticEuropeanEngine)
├─ American          (Binomial CRR N=1000 o FD Crank-Nicolson)
└─ Bermudan          (Bermudan exercise schedule + LSM Longstaff-Schwartz MC)

Exotic
├─ Barrier
│   ├─ Knock-In  (UI/DI/UO/DO continuous + discrete monitoring)
│   └─ Knock-Out (idem + rebate)
├─ Asian
│   ├─ Arithmetic (Turnbull-Wakeman approx o MC)
│   └─ Geometric  (closed-form Kemna-Vorst)
├─ Lookback        (floating/fixed strike)
├─ Digital/Binary  (cash-or-nothing, asset-or-nothing)
└─ Cliquet         (forward-starting series)

Structured Products
├─ Autocallable      (worst-of basket + memory coupon + early redemption barriers)
├─ Reverse Convertible (short put + bond)
├─ Capital-Protected Note (zero-coupon bond + long call basket)
├─ Phoenix           (autocallable variant + memory coupon)
└─ Twin-Win          (long ATM call + long OTM put barrier)

Interest Rate Derivatives
├─ Cap/Floor         (strip caplet/floorlet, Black 76 model)
├─ Swaption          (European: Black-76, Bermudan: G2++)
├─ CMS Spread Option (correlation + replication caplet/floorlet basket)
└─ Inflation Swap    (BLS index + seasonality)
```

### 1.3 Greeks supportati (1° + 2° ordine)

```python
greeks = {
    # Primary (1° ordine)
    "delta":  ∂V/∂S,        # equity sensitivity
    "vega":   ∂V/∂σ,        # vol sensitivity (per 1% absolute)
    "theta":  ∂V/∂t,        # time decay (per day)
    "rho":    ∂V/∂r,        # interest rate sensitivity (per 1bp)
    "epsilon": ∂V/∂q,       # dividend yield sensitivity (per 1%)

    # Secondary (2° ordine)
    "gamma":   ∂²V/∂S²,     # delta sensitivity
    "vanna":   ∂²V/∂S∂σ,    # delta-vega cross
    "volga":   ∂²V/∂σ²,     # vega convexity (vomma)
    "charm":   ∂²V/∂S∂t,    # delta decay
    "veta":    ∂²V/∂σ∂t,    # vega decay
    "speed":   ∂³V/∂S³,     # gamma rate of change (3° ordine, opzionale)
}
```

### 1.4 Volatility surface

#### SABR calibration
```
σ_BS(K, T) = SABR(α, β, ρ, ν; F, T)
```
- α: ATM vol level
- β: backbone slope (β=1 lognormal CEV, β=0 normal, β=0.5 stochastic vol)
- ρ: spot-vol correlation (skew)
- ν: vol-of-vol (smile curvature)

Calibration: Levenberg-Marquardt fit su market quotes BBG/Refinitiv per OPT_VOL_LAST.

#### SVI parametrization (Gatheral)
```
w(k) = a + b * (ρ * (k - m) + sqrt((k - m)² + σ²))
```
Arb-free check: Gatheral-Jacquier no-butterfly + no-calendar arbitrage.

### 1.5 Output strutturato Pydantic v2

```python
{
  "pricingId": "uuid",
  "tenantSlug": "ws",
  "asOfDate": "2026-05-03",
  "asOfTime": "2026-05-03T14:00:00Z",
  "product": {
    "type": "european_call",  # european_call|european_put|american_call|...|autocallable|reverse_convertible|...
    "underlying": "AAPL",
    "strike": 200.0,
    "maturity": "2026-12-19",
    "currency": "USD",
    "quantity": 100
  },
  "marketData": {
    "spot": 195.50,
    "rfRate": 0.0455,
    "dividendYield": 0.0045,
    "impliedVol": 0.265,        # ATM σ used (or surface lookup)
    "volSurfaceId": "uuid"      # se surface lookup
  },
  "engine": "AnalyticEuropeanEngine",
  "result": {
    "npv": 8.42,                # net present value per share
    "ccyValue": 842.0,          # quantity * npv (in product currency)
    "implied": {                # implied calc se quote market disponibile
      "marketPrice": 8.50,
      "impliedVol": 0.268
    }
  },
  "greeks": {
    "delta": 0.532, "gamma": 0.0184, "vega": 0.482, "theta": -0.0183,
    "rho": 0.291, "epsilon": -0.234, "vanna": -0.0072, "volga": 0.84,
    "charm": -0.0014, "veta": 0.0091
  },
  "scenarios": [                # ex-ante stress test 5 scenari MIFID II art. 50
    { "name": "spot+10%",      "delta_npv": +89.2,  "delta_pct": +0.106 },
    { "name": "spot-10%",      "delta_npv": -82.1,  "delta_pct": -0.097 },
    { "name": "vol+25%",       "delta_npv": +12.4,  "delta_pct": +0.015 },
    { "name": "vol-25%",       "delta_npv": -11.8,  "delta_pct": -0.014 },
    { "name": "rates+100bps",  "delta_npv": +2.91,  "delta_pct": +0.003 }
  ],
  "warnings": [                 # PROTOTYPE-PHASE flags
    "MIFID II PRIIPs KID auto-generation V22+ milestone — currently no KID published",
    "ESMA suitability test client-side V21+ milestone"
  ]
}
```

### 1.6 Persona visibility (MIFID II posture prototype-phase)

- **ADVISOR** (ws+az): vede SOLO pricings/strategies proprie (filter `userId` su `DerivativePricing.requestedBy`)
- **RELATIONSHIP_MANAGER**: idem ADVISOR
- **SUPERVISOR/ADMIN**: cross-tenant + vol surface upload + structured product creation + tier override
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto — derivati sono complex products MIFID II, il cliente non accede mai a pricing/Greeks. L'advisor propone hedging overlay → cliente firma post-suitability test (V21+) + KID PRIIPs (V22+).

### 1.7 Tier presets

| Tier | Engines abilitati | use case |
|---|---|---|
| `derivatives-standard` | BS analytic, Binomial CRR, FD CN, Heston analytic, SABR | default ws+az ADVISOR |
| `derivatives-uhnw` | tutti + MC Heston-HullWhite, Bates jump-diffusion, G2++ swaption Bermudan, TF-Quant-Finance GPU batch | UHNW + family office, structured products |

Override env (priorità: env > tier preset):
- `DERIVATIVES_DEFAULT_ENGINE_EUROPEAN` (default `AnalyticEuropeanEngine`)
- `DERIVATIVES_DEFAULT_ENGINE_AMERICAN` (default `BinomialVanillaEngine`)
- `DERIVATIVES_MC_PATHS` (default `100000` per MC engine)
- `DERIVATIVES_FD_GRID` (default `100x100` Crank-Nicolson)
- `DERIVATIVES_TF_GPU_ENABLED` (default `false`, set `true` se GPU available)

---

## §2 · Pattern di codice (esempi realistici)

### 2.1 European option Black-Scholes (QuantLib-Python)

```python
# services/derivatives-pricing-py/engines/european.py
from __future__ import annotations
import QuantLib as ql
from .contracts import PricingRequest, PricingOutput

def price_european(req: PricingRequest) -> PricingOutput:
    """
    European call/put Black-Scholes-Merton via QuantLib AnalyticEuropeanEngine.
    Closed-form, sub-millisecond.
    """
    # 1. Calendar + day count
    calendar = ql.UnitedStates(ql.UnitedStates.NYSE)
    day_count = ql.Actual365Fixed()
    today = ql.Date.from_date(req.as_of_date)
    ql.Settings.instance().evaluationDate = today

    # 2. Term structures
    spot = ql.SimpleQuote(req.spot)
    spot_handle = ql.QuoteHandle(spot)
    rf_curve = ql.YieldTermStructureHandle(
        ql.FlatForward(today, req.rf_rate, day_count)
    )
    div_curve = ql.YieldTermStructureHandle(
        ql.FlatForward(today, req.dividend_yield, day_count

…[truncato — apri il file MD per testo completo]