REST API Overview

Base URL: $DERIVFABRIC_BASE_URL — your deployment's address. DerivFabric is deployed per customer, so there is no shared host.

All endpoints accept POST with Content-Type: application/json. Field names use camelCase.

Authentication

Every request carries your API key in the X-API-Key header. The single exception is /health, which needs no key so a load balancer can probe it.

export DERIVFABRIC_BASE_URL=https://your-deployment.example
export DERIVFABRIC_API_KEY=df_live_...

Keys carry scopes, and an endpoint refuses a key that lacks the one it requires. See Authentication for the scope list and how to obtain a key.

Conventions

• Numbers are double-precision JSON numbers.
• Rates and volatilities are decimals, not percentages (0.05 = 5%).
• Time is in years unless an endpoint explicitly expects calendar dates.
• optionType is string-based. "put" is parsed as put, any other value is treated as call.

Quick Start

Health check:

curl -s "$DERIVFABRIC_BASE_URL/health" | jq

Vanilla price:

curl -s "$DERIVFABRIC_BASE_URL/api/v1/price" \
  -H "X-API-Key: $DERIVFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spot": 100,
    "strike": 100,
    "rate": 0.05,
    "dividend": 0.0,
    "volatility": 0.20,
    "time": 1.0,
    "optionType": "call"
  }' | jq

Endpoints

Health

Method	Path	Description
GET	/health	Health check

Vanilla Pricing

Method	Path	Description
POST	/api/v1/price	Price a single vanilla option (BS)
POST	/api/v1/greeks	Full Greeks for a vanilla option
POST	/api/v1/implied-vol	Implied volatility from market price
POST	/api/v1/batch/price	Batch price multiple options
POST	/api/v1/batch/greeks	Batch Greeks for multiple options

Contract DSL

Method	Path	Description
POST	/api/v1/contract/price	Price any DSL contract (MC)
POST	/api/v1/contract/describe	Human-readable contract description
POST	/api/v1/contract/greeks	Contract price + Greeks (bump-and-reprice)
POST	/api/v1/strategy/price	Price a named strategy

American Options

Method	Path	Description
POST	/api/v1/american/price	American option via LSM

Convertible Bonds

Method	Path	Description
POST	/api/v1/convertible/price	Convertible bond (tree/T-F)

Calibration

Method	Path	Description
POST	/api/v1/calibrate/sabr	Calibrate SABR model
POST	/api/v1/calibrate/heston	Calibrate Heston model
POST	/api/v1/calibrate/curve	Bootstrap yield curve

Portfolio

Method	Path	Description
POST	/api/v1/portfolio/price	Price vanilla options portfolio
POST	/api/v1/portfolio/var	Delta-normal VaR
POST	/api/v1/portfolio/stress	Spot and vol stress testing
POST	/api/v1/portfolio/mixed	Mixed instrument portfolio
POST	/api/v1/portfolio/hedgeopt	Hedge optimization

Hedging

Method	Path	Description
POST	/api/v1/hedge/optimize	Hedge optimization

XVA

Method	Path	Description
POST	/api/v1/xva/calculate	CVA/DVA/FVA/KVA calculation

Error responses

All errors return:

{
  "error": "Human-readable error message"
}

Typical status codes:

• 400 Bad Request: currently used by /api/v1/implied-vol for invalid inversion input.
• 500 Internal Server Error: used by most domain endpoints when pricing/calibration/optimization fails.

/health returns 200 OK on success.