API — Greeks

Greek trace - forward (time × price) projection

Black-Scholes forward projection of dealer gamma, charm, or vanna across a (time × price) grid, holding today’s chain constant and decaying τ toward each contract’s expiry.

Returns a 2D field of cell values, the time_axis_ms and price_axis it’s keyed on, and the contracts it consumed. Intended for desk-grade dealer-positioning visualisations (the BackQuant Pro Terminal’s TRACE panel runs the same math client-side).

Sign convention: +1 for calls, −1 for puts — positive cell = call book dominates the put book at that (time, price).

Units:

gamma → $ per 1% spot move (γ × S² × OI × 0.01).
charm → 1/year (∂Δ/∂τ × OI).
vanna → per IV unit (∂Δ/∂σ × OI).

Performance: the field is computed on cache miss in ~50–100 ms for typical grids. Cached for 30 s per (symbol, full-param-hash) so identical repeated calls are essentially free.

What-if vol shifts: vol_shift_pct multiplies every contract’s σ by 1 + vol_shift_pct/100 before evaluation. Lets you build vol-up / vol-down surfaces without re-fetching.

GET

options

greeks

trace

{greek}

Forward (time × price) greek projection — gamma / charm / vanna

curl --request GET \
  --url https://api.example.com/options/greeks/trace/{greek} \
  --header 'X-API-Key: <api-key>'

{
  "data": {
    "expiry": "<string>",
    "spot_price": 123,
    "vol_shift_pct": 123,
    "field_units": "<string>",
    "time_axis_ms": [
      123
    ],
    "price_axis": [
      123
    ],
    "field": [
      [
        123
      ]
    ],
    "field_min": 123,
    "field_max": 123,
    "abs_field_max": 123,
    "contracts_used": 123,
    "expiries_in_window": [
      "<string>"
    ],
    "tau_floor_seconds": 123
  },
  "meta": {
    "version": "<string>",
    "timestamp": "<string>",
    "request_id": "<string>",
    "symbol": "<string>",
    "spot_price": 123,
    "computed_at": "<string>",
    "freshness_seconds": 123,
    "source": [
      "<string>"
    ],
    "exchanges_filtered": [
      "<string>"
    ],
    "rate_limit": {},
    "extra": {}
  },
  "success": true
}

Forward Black-Scholes projection of dealer gamma, charm, or vanna across a (time × price) grid - the same view that powers BackQuant Pro’s TRACE panel, exposed as raw data for your own renderer. Holding today’s chain constant, the endpoint walks each point on the grid (a future timestamp + a future spot price), recomputes per-contract τ and the requested greek under those conditions, sums across the chain weighted by per-contract OI, and returns the resulting field.

Why use it

A single point-in-time greek profile only tells you what dealer exposure looks like now. Trace tells you what it’ll look like as time and price evolve - where gamma walls develop, decay, or migrate as τ runs to zero. It’s the difference between a snapshot and a forward map. Common uses:

Intraday flow planning - greek=gamma&expiry=0dte shows where 0DTE dealer hedging will concentrate as the session progresses.
Charm bleed - greek=charm exposes the passive delta drift dealers will accumulate from time alone, even with spot frozen.
Vol-shock surfaces - vol_shift_pct=±10 builds an instant what-if view for vol up / down without a re-fetch.
Multi-day overlays - expiry=all&horizon_hours=168 projects across the next week’s term structure.

Sign convention

+1 for calls, −1 for puts. A positive cell value means the call book dominates the put book at that (time, price) - supportive flow. A negative cell means the reverse. Identical to the rest of the BackQuant stack so cross-references between TRACE and the per-strike profiles are coherent.

Units

`greek`	Unit	Formula per cell
`gamma`	$ per 1% spot move	`Σ sign × γ × S² × OI × 0.01`
`charm`	per year	`Σ sign × ∂Δ/∂τ × OI`
`vanna`	per IV unit	`Σ sign × ∂Δ/∂σ × OI`

field_units is echoed on every response so renderers don’t need to hardcode this.

Cells, axes, and shape

The response body is rectangular:

field[t][p]   ← cell value at time_axis_ms[t], price_axis[p]

time_axis_ms runs from “now” to now + horizon_hours. price_axis runs from spot × (1 − range/100) to spot × (1 + range/100). Both are evenly spaced. abs_field_max = max(|field_min|, |field_max|) is included to make symmetric colour scales trivial: value / abs_field_max clamped to [−1, +1] is the standard input for diverging palettes.

What-if vol shifts

vol_shift_pct adds a flat percent shift to every contract’s IV - e.g. vol_shift_pct=5 multiplies each σ by 1.05 before evaluation. Use it to build vol-up / vol-down surfaces in two requests instead of waiting for an actual vol move.

Performance

Cached for 30 seconds per (symbol, full-param-hash). Identical repeated calls are essentially free; varying any parameter (greek, expiry, grid resolution, vol shift, OI threshold) creates a fresh cache entry. Cold compute is typically 50–100 ms for default grid sizes; payload runs 30–80 KB of JSON.

Caps

Param	Min	Max	Default
`time_steps`	2	200	60
`price_steps`	2	200	80
`price_range_pct`	>0	50	8
`horizon_hours`	>0	720	24
`vol_shift_pct`	−50	+50	0
`min_oi`	0	-	0

Going past the caps returns a VALIDATION_ERROR with a 422.

Greeks beyond delta

Greek profile

Greek surfaces

3D greek surface

Authorizations

X-API-Key

string

header

required

Your BackQuant API key (same key as v1)

Headers

X-API-Key

string | null

Path Parameters

greek

enum<string>

required

Which greek to project.

Available options:

gamma,

charm,

vanna

Query Parameters

symbol

enum<string>

default:BTCUSDT

Trading symbol: BTCUSDT, ETHUSDT, SOLUSDT, or HYPEUSDT.

Available options:

BTCUSDT,

ETHUSDT,

SOLUSDT,

HYPEUSDT

expiry

string

default:0dte

Expiry filter. 0dte = today's UTC expiries only (the standard intraday read), all = every active expiry, or a specific Deribit token (e.g. 28MAR25).

time_steps

integer

default:60

Number of buckets along the time axis. Higher = smoother surface, larger payload. Capped at 200.

Required range: 2 <= x <= 200

price_steps

integer

default:80

Number of buckets along the price axis. Higher = smoother, larger payload. Capped at 200.

Required range: 2 <= x <= 200

price_range_pct

number

default:8

Price half-width as a percent of spot. Default 8 = ±8% around spot. Capped at ±50% — wider than that and BS gamma at the wings is essentially zero anyway.

Required range: x <= 50

horizon_hours

number

default:24

Time horizon in hours from now. Default 24 = one trading day. Use longer horizons for multi-week trace overlays — capped at 720 h (30 days).

Required range: x <= 720

vol_shift_pct

number

default:0

What-if shift applied to every contract's IV (additive percent of σ — +5 ⇒ multiply σ by 1.05). Use to build vol-up / vol-down surfaces without re-fetching.

Required range: -50 <= x <= 50

min_oi

number

default:0

Drop contracts with OI below this threshold before summing. Useful for de-noising the wings.

Required range: x >= 0

Response

Successful Response

data

TraceData · object

required

Single forward-projected greek field.

Show child attributes

Documentation Index

​Why use it

​Sign convention

​Units

​Cells, axes, and shape

​What-if vol shifts

​Performance

​Caps

​See also

Greeks beyond delta

Greek profile

Greek surfaces

3D greek surface

Authorizations

Headers

Path Parameters

Query Parameters

Response

Why use it

Sign convention

Units

Cells, axes, and shape

What-if vol shifts

Performance

Caps

See also