Oracles

This page describes the data sources and rules Hypercall uses for:

• Underlying prices (spot and forward/mark)
• Settlement reference prices (expiry TWAP)
• Implied volatility (IV) / vol surface

---

Terminology

Hyperliquid's metaAndAssetCtxs response contains several price fields. Hypercall uses them as follows:

Field	Description	Usage
oraclePx	External spot/index price	Canonical spot input for all pricing
markPx	Hyperliquid's mark price (oracle plus premium adjustment)	Not used as canonical spot
midPx	Mid price from the Hyperliquid orderbook	Reference only
impactPxs	Slippage-aware prices	Reference only

Forward/Mark-to-Expiry Price

In Hypercall, "mark price" may also refer to a forward price computed as:

$$F = S \times e^{r \cdot t}$$

Where:

• $S$ is the oracle/index spot (oraclePx)
• $r$ is the risk-free rate
• $t$ is time to expiry (in years)

This forward price is used for greeks, risk calculations, and other computations that depend on the forward rather than spot.

---

Underlying Price Oracle

Purpose

The underlying price oracle provides real-time spot prices used for:

• Options pricing and greeks
• Margin calculations
• Risk monitoring
• Mark-to-market valuations

Data Source

Hyperliquid Info API (https://api.hyperliquid.xyz/info)

We ingest the oraclePx field from metaAndAssetCtxs for each supported underlying asset.

Forward Price

For any option series with a future expiry, Hypercall computes a forward price using the formula above. This ensures pricing consistency with time-to-expiry across all risk and valuation calculations.

---

Settlement Oracle

Purpose

The settlement oracle determines the reference price used to cash-settle Exchange options at expiry.

Settlement Rules

Parameter	Value
Expiry time	Mainnet SPCX: 4:00 PM ET. Testnet currently: 08:00 UTC
Reference price	30-minute TWAP of oraclePx
TWAP window	[expiry - 30 minutes, expiry]

How It Works

At expiry, Exchange positions are cash-settled using a 30-minute Time-Weighted Average Price (TWAP) of the underlying's oracle spot price. The TWAP smooths out short-term volatility and provides a manipulation-resistant settlement reference.

Settlement uses the finalized TWAP only. If the finalized settlement price is not available when the contract expires, the instrument stays in Expired Pending Price: trading is disabled, open orders are cancelled, and settlement retries until the finalized oracle price is available.

TWAP Calculation Method

The settlement price is computed using a median-of-means algorithm with 5% trimming:

1. Collect samples: Gather $n$ price samples $\{p_1, p_2, \ldots, p_n\}$ during the window
2. Trim outliers: Sort and remove 5% from each tail, yielding trimmed set $P'$ of size $n' = 0.9n$
3. Partition into buckets: Divide $P'$ into $k \approx \sqrt{n'}$ equal-sized buckets $B_1, B_2, \ldots, B_k$
4. Compute bucket means:

$$\mu_i = \frac{1}{|B_i|} \sum_{p \in B_i} p$$

5. Final settlement price:

$$P_{\text{settlement}} = \text{median}(\mu_1, \mu_2, \ldots, \mu_k)$$

This approach is more robust than a simple average, as it resists manipulation from brief price spikes or flash crashes during the settlement window.

---

Implied Volatility Oracle

Purpose

The IV oracle provides the volatility surface used for:

• Options pricing (Black-Scholes inputs)
• Vega risk calculations
• Margin requirements

Source Handling

Hypercall maintains implied volatility surfaces for supported markets.

See Volatility Oracle for closed-session handling and fail-closed behavior.

Vol Surface

Hypercall maintains an in-memory volatility surface per underlying, with:

• Strike-specific IV for configured strikes
• ATM IV as a baseline reference
• Interpolation across strikes and expiries when exact data points are unavailable

Staleness Handling

If required volatility data is unavailable or stale, the system fails closed for calculations that depend on that IV. Markets with closed source sessions can use a session-aware model that transforms the last good source surface, but only when all required inputs are valid.