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, currently 5%
• $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 WebSocket API (wss://api.hyperliquid.xyz/ws)

We read the oraclePx field for each supported underlying from Hyperliquid's activeAssetCtx WebSocket subscription (the same asset context fields that metaAndAssetCtxs returns) and sample it every 2 seconds. There is no HTTP polling fallback: while the feed is down or stale, the oracle is marked unhealthy and no new price is recorded.

Underlying	Hyperliquid market
BTC, ETH	Main perp dex: BTC, ETH
SPCX, SP500, BOT, MU, NVDA, META, MSFT, AAPL, SNDK, BABA	xyz HIP-3 perp dex: xyz:SPCX, xyz:SP500, xyz:NVDA, and so on

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	BTC and ETH: 08:00 UTC. All other underlyings: 20:00 UTC (4:00 PM New York time while US daylight saving time is in effect)
Reference price	30-minute TWAP of oraclePx
TWAP window	[expiry - 30 minutes, expiry]
Minimum samples	500

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 Hypercall collected fewer than 500 samples in the window (for example after a restart inside it), it can rebuild the window from archived Hyperliquid oracle history under the same 500-sample minimum. If the finalized settlement price is still 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

Each underlying has one configured volatility source: Deribit for BTC and ETH, US listed options data for equity and index underlyings, and realized volatility for BOT. See Volatility Oracle for the table. The engine checks the source, the snapshot age and the surface itself before using one.

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. When the US options market is closed, equity and index surfaces come from the snapshot taken at the last session close. See Volatility Oracle for the age limits.