Skip to main content

Contract DSL Guide

The Contract DSL lets you describe any financial payoff as a composable expression. The API accepts a JSON ContractSpec and evaluates it via Monte Carlo.

Building blocks​

Every contract is built from these primitives:

{"type": "vanilla_call", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"}
{"type": "vanilla_put",  "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"}

Composition operators​

Combined (both execute)​

A straddle is a call + put at the same strike:

{
  "type": "combined",
  "specs": [
    {"type": "vanilla_call", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"},
    {"type": "vanilla_put",  "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"}
  ]
}

Negated (short position)​

A bull call spread: long the lower strike, short the upper:

{
  "type": "combined",
  "specs": [
    {"type": "vanilla_call", "underlying": "SPX", "strike": 95, "expiry": "2026-12-31"},
    {"type": "negated", "spec": {"type": "vanilla_call", "underlying": "SPX", "strike": 105, "expiry": "2026-12-31"}}
  ]
}

Scaled​

Scale a contract by notional or quantity:

{"type": "scaled", "contract": {"type": "vanilla_call", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"}, "factor": 1000}

Conditional​

Apply a barrier condition:

{
  "type": "conditional",
  "contract": {"type": "vanilla_call", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"},
  "condition": {"type": "barrier_condition", "level": 90, "direction": "down", "style": "knock_out"}
}

Choice (best of two)​

The holder picks whichever is more valuable (models American-style exercise):

{
  "type": "choice",
  "left":  {"type": "vanilla_call", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"},
  "right": {"type": "vanilla_put",  "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"}
}

Pre-built strategies​

For common multi-leg strategies, use the strategy shortcut:

# Straddle
curl -X POST "$DERIVFABRIC_BASE_URL/api/v1/strategy/price" \
  -H "X-API-Key: $DERIVFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": {"strategy": "straddle", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"},
    "market": {"spot": 100, "rate": 0.05, "volatility": 0.20}
  }'

Available strategies: straddle, strangle, bull_call_spread, bear_put_spread, iron_condor, butterfly, collar.

Describing contracts​

Get a human-readable description without pricing:

curl -X POST "$DERIVFABRIC_BASE_URL/api/v1/contract/describe" \
  -H "X-API-Key: $DERIVFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract": {"type": "strategy", "strategy": "iron_condor", "underlying": "SPX", "put_buy": 90, "put_sell": 95, "call_sell": 105, "call_buy": 110, "expiry": "2026-12-31"}}'

Returns: {"description": "IronCondor(SPX, 90/95/105/110)"}.

Greeks​

Bump-and-reprice Greeks for any contract:

curl -X POST "$DERIVFABRIC_BASE_URL/api/v1/contract/greeks" \
  -H "X-API-Key: $DERIVFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract": {"type": "vanilla_call", "underlying": "SPX", "strike": 100, "expiry": "2026-12-31"},
    "market": {"spot": 100, "rate": 0.05, "volatility": 0.20}
  }'

See DSL Architecture for the full specification.