HIP-3 Builder's Guide: Why Oracle Definition Shapes Your Perpetual Market's Destiny

When Hyperliquid rolled out HIP-3, it fundamentally changed how perpetual contract markets come into existence. Instead of gatekeeping market listings behind a centralized approval process, the protocol opened access to qualified builders—but this freedom came with a catch: builders now own the operational risk. The cornerstone of this responsibility begins with a single, often underestimated decision: your oracle definition.

Over three months since mainnet launch, builder-deployed markets on HIP-3 have already accumulated more than $13 billion in transaction volume. That scale didn’t happen by accident. It reflects both the protocol’s innovation and the builders who successfully navigated its complexity. Yet for every successful market, there’s a cautionary tale—like the December 2025 incident on trade.xyz where an attacker exploited weak oracle definition on a non-24/7 asset, draining $13 million in long positions through price manipulation.

This guide walks you through the architecture, risks, and proven control strategies that separate thriving markets from those that spiral into liquidation cascades and ADL triggers.

Understanding Hyperliquid’s Infrastructure: The Foundation for Oracle Definition

Hyperliquid doesn’t ask builders to reinvent the wheel. It provides a two-tier infrastructure:

HyperCore: A custom Layer 1 blockchain optimized for perpetual trading, processing 200,000 orders per second with deterministic finality. Matching, clearing, and settlement all happen at the protocol level—meaning builders don’t build trading engines from scratch.

HyperEVM: The application layer running smart contracts, compatible with existing Ethereum tooling.

By reusing these infrastructure layers, builders focus on what matters: market definition and operational discipline. The native Hyperliquid perpetual marketplace still follows traditional CEX listing processes—validators vote on which contracts to include. But HIP-3 inverts this model: any builder meeting the threshold can launch.

To launch under HIP-3, you must stake 500,000 HYPE tokens. Your first three markets deploy for free; additional markets require bidding in a Dutch auction system (31-hour cycles, starting at 2x the previous round’s final price). The staking requirement persists for 30 days even if you suspend all markets—this isn’t optional insurance; it’s your accountability mechanism.

Your Role as a Builder: Two Distinct Responsibilities

HIP-3 divides builder work into two phases: market definition and market operation.

Market Definition is about getting it right from day one. You must specify:

1. Oracle definition: Which data source will anchor prices? What’s your initial oracle price (oraclePx)? For a stock perpetual, is that Pyth? For a less liquid altcoin, is it a CEX price feed? This decision is irreversible once traders enter positions.

2. Contract specifications: Symbol, minimum order size, maximum leverage, collateral asset (USDC, for example), and margin tables that tie leverage limits to position size.

Market Operation means continuous vigilance:

• Price feeding: You call setOracle repeatedly to submit oracle prices. There must be at least 2.5 seconds between calls; if your mark price (optional) isn’t updated within 10 seconds, the system reverts to local order book pricing.
• Leverage adjustment: You bind margin tables to your market, setting tiered leverage limits based on notional position size.
• Emergency controls: You can invoke haltTrading to freeze the market, cancel all orders, and settle positions at the current mark price.

The protocol imposes guardrails—mark price can’t move more than ±1% per update, and all prices clamp within 10x the start-of-day value. But guardrails aren’t handcuffs. Inside those constraints, your choices determine whether your market thrives or implodes.

Oracle Definition: The Critical Decision Point for Market Stability

Oracle definition is where your market’s destiny diverges. It’s the first thing you set and the hardest thing to fix. Here’s why it matters so much.

What Oracle Definition Actually Means

Oracle definition in HIP-3 encompasses three layers:

1. OraclePx (required): The primary price anchor. It’s typically sourced from your relayer server, which aggregates external feeds (Pyth, DEX AMMs, CEX prices). This is your single point of failure if the relayer crashes or gets DDoS’d.

2. MarkPx (optional): Custom mark prices you submit—up to 2 sets—to calculate the actual liquidation benchmark. This is where builders with proprietary pricing models shine, but also where bad judgment kills markets.

3. ExternalPerpPx (required): The weighted median of perp mid-prices from multiple CEXs. This acts as a sanity check, preventing your isolated market from drifting too far from broader market consensus.

The system then combines these into a final mark price: median of (local order book mid, your submitted markPx sets, and externalPerpPx). If any layer fails, the system cascades to the next. If all fail, you’re trading blind.

24/7 vs. Non-24/7 Assets: Two Different Oracle Definitions

For 24/7 assets (BTC, ETH, most altcoins): Oracle definition is straightforward. Pyth, Chainlink, or direct CEX feeds provide continuous, liquid price signals. Your relayer aggregates them. Manipulation is expensive because spotting mispricings against dozens of external markets is immediate.

For non-24/7 assets (stocks, indices, commodities): Oracle definition becomes existential. Take NASDAQ stocks. During market hours, Pyth delivers clean prices. At market close, there’s no external price. Your oracle definition now has to survive in a vacuum.

Here’s the trap: During off-hours, your setOracle mechanism can’t fetch a real market price. So you fall back on “last close + internal order book pressure.” But without an external anchor, internal pressure alone becomes a mirror—the price reflects only what’s inside your market, not the underlying asset’s true value.

The protocol enforces a ±1/maxLeverage cap on price movement (e.g., 10x leverage → 10% max swing). On high-volatility assets during normal hours, that’s reasonable. On a low-liquidity stock on a weekend with zero external prices, a 10% swing is enough to liquidate entire portfolios and trigger ADL cascades.

Liquidation & ADL: How Oracle Definition Impacts Cascade Risks

Once positions are open, oracle definition determines when traders get margin-called.

The Liquidation Trigger

Liquidation happens when your isolated position value drops below maintenance margin requirements. The check uses the mark price (calculated from your oracle definition), not any specific transaction price. Mathematically:

Liquidation Price = (notional value × marginRequirement) / position size

The maintenance margin requirement itself is tiered—higher leverage gets a tighter margin, which means liquidation happens sooner. Your margin table binds these tiers to your market, so if you set unreasonably high leverage on a low-liquidity market, liquidations cluster.

When Liquidation Becomes ADL

The real horror starts when liquidation orders can’t find buyers. Imagine your mark price shows $3,000 (calculated from your oracle definition), but actual order book depth is thin. Liquidation orders execute at $2,910—a 3% gap. If that gap is large enough that liquidation losses exceed the trader’s margin, you’ve created “bad debt.”

The system doesn’t tolerate bad debt. It triggers ADL (Auto-Deleveraging): profitable positions on the opposite side are force-closed at the previous mark price ($3,000), not the current market price. Profits get clawed back to fill the gap, transferring the loss to the winners.

From a builder’s perspective, ADL is a contagion warning. Each ADL event signals that your market is under stress—either your oracle definition is broken, or your leverage settings invited too much risk into shallow order books.

Critical Parameters: Configuring Oracle Definition and Leverage for Your Market

Your setOracle implementation is a tuning dial with immense leverage. Mistakes cascade.

Oracle Frequency & Update Rules

You must call setOracle at least every 10 seconds, or the system reverts to local order book pricing (stranding the mark price if your feeds are better-informed). Most builders push updates every 2-5 seconds during volatile periods.

But here’s the gotcha: Each setOracle call can move the mark price by at most ±1%. If real market conditions shift 5% in one second (not unusual for low-cap altcoins or black swan events), your oracle definition is now stale by necessity. Liquidators see stale prices and hammer the market.

Non-24/7 Asset Oracle Definition: The Weekend Problem

Stocks and traditional assets don’t trade weekends. A builder planning stock perps on HIP-3 must decide: How do you define oracle prices on Saturday morning when there’s no exchange open?

Current approaches:

Approach 1: Conservative – Suspend trading or liquidations during off-hours. Lighter protocol and Optium do this. Traders lose 24/7 access, but the market stays stable.

Approach 2: Internal Pricing – Use “last external price + internal order book” to maintain operation. This is what trade.xyz attempted before their December incident.

Approach 2 exposes a critical weakness in oracle definition: the ±1/maxLeverage price floor becomes a ceiling for risk. On a low-liquidity stock on a Sunday, even a 10% price move might occur with a handful of large orders. Your oracle definition has to prevent this, but the guardrails aren’t tight enough.

A better oracle definition for non-24/7 assets incorporates supplemental anchors:

• Blue Ocean ATS: Provides after-hours equity pricing. Not as liquid as regular trading hours, but it’s real market prices, not internal order book estimates.
• IG Weekend CFD quotes: Offer “expected opening move” signals. Combined with last close + internal price, they give your oracle definition a fighting chance of staying anchored.

These supplements don’t replace rigorous oracle design—they augment it. Your oracle definition should be: “During market hours, Pyth. During off-hours, last Pyth close adjusted by Blue Ocean ATS mid + internal order book pressure, clamped to ±X%.”

Oracle Risk Control: Real-Time Monitoring Strategies for Price Feed Stability

Here’s where theory meets operations. Your oracle definition is only as good as its monitoring system.

Price Feed Failure Detection

Your relayer is a single point of failure. If the process crashes or loses network connectivity, setOracle stops firing. Within 10 seconds, the system falls back to pure order book pricing. For liquid markets with tight spreads, this is survivable. For everything else, it’s a liquidation trap.

Action plan:

• Level 1 alert: Price feed down >2.5 seconds. Run immediate health check on your relayer nodes. Switch to backup infrastructure. Publish status report.
• Level 2 alert: Price feed down >10 seconds. Call setOpenInterestCaps to freeze new positions. Existing positions can still close. This prevents cascading liquidations while you rebuild the oracle pipeline.

Price De-Anchoring: When Your Oracle Definition Drifts

Even if your relayer is online, your oracle prices can drift far from reality. This happens when:

• Your Pyth feed is slightly stale (happens during congestion).
• Internal order book mid-price diverges due to low liquidity.
• External CEX prices (used in externalPerpPx) are moving faster than your updates.

Define de-anchoring quantitatively:

• Threshold A: |oraclePx - externalPerpPx| > 2%.
• Threshold B: |markPx - local order book mid| > 1%.
• Threshold C & D: Similar measures for sustained (>5 second) deviations.

Action plan:

• Level 1: If 2+ thresholds triggered, call setOpenInterestCaps to lock new position growth.
• Level 2: Gradually update margin tables, reducing max leverage tier-by-tier. Enable the setOracle ±1% clamp as a safety mechanism.
• Level 3: Continue Level 2 actions while issuing alerts. If deviations persist >30 seconds, invoke haltTrading as a last resort.

Order Book Degradation: Detecting Thin Markets

Liquidity can vanish without your oracle definition failing. Track:

• Depth band (±x%): Total order volume within x% of mid-price. Typical: ±0.5% depth.
• Spread: bestAsk - bestBid. Healthy: <0.1%. Dangerous: >1%.
• Aggressive volume: Taker volume in the last Δt seconds. If this exceeds your depth band, you have a problem.

When depth collapses while aggressive volume spikes, liquidation orders will face slippage. This is your signal to reduce open interest caps before ADL cascades.

Non-24/7 Assets: Oracle Definition During Market Closures

Let’s drill into the specific nightmare: stocks perpetuals on a Friday evening. Market closes at 4 PM ET. Your builder-configured oracle definition has to carry the market through the weekend.

The December 2025 Trade.xyz Breakdown

On December 14, 2025, attackers exploited exactly this scenario. They built a large short position in XYZ100 (a NASDAQ-100 index perp) when the market was illiquid. The attack:

1. Off-hours positioning: After market close, with minimal external price anchors and thin order books, they created massive selling pressure.
2. Oracle definition failure: The internal mark price (based on limited internal trades + last external price) diverged upward relative to where buyers existed.
3. Liquidation cascade: Long positions got margin-called at artificially high prices. Liquidation orders further tanked the market.
4. ADL cascade: System force-closed profitable short positions (including the attacker’s) at stale mark prices, but the gap was so large that $13M in ADL events cascaded.

The root cause: oracle definition for off-hours non-24/7 assets was too loose. A 10% leverage-based price cap sounds rigid until you realize that’s 10 percentage points of latitude on a stock that might only move 2-3% real dollars in regular trading.

Better Oracle Definition for Off-Hours

Your oracle definition for non-24/7 assets should include:

1. Primary anchor during hours: Pyth or exchange feeds.
2. Supplemental off-hours anchor: Blue Ocean ATS or IG CFD quotes to signal expected opening gaps.
3. Internal sanity check: If the internal order book mid deviates >X% from the supplemental anchor, trigger alerts and reduce leverage.
4. Asymmetric risk management: During hours, you can run 10x leverage. Off-hours, drop to 2-5x max leverage. This reduces liquidation cascade risk when oracle definition is fundamentally handicapped by lack of external prices.

Building Your Risk Dashboard: Price, Depth, and Position Monitoring

Professional builders operate three monitoring channels simultaneously:

Channel 1: Price-Side Indicators

Track oracle health every 1-2 seconds:

• Feed latency (time since last setOracle call)
• Price deviation from external benchmarks
• Clamp breaches (price at ±1% limits for sustained periods)

Channel 2: Order Book Indicators

Monitor depth and spread every 5-10 seconds:

• Depth at ±0.5%, ±1%, ±2% from mid
• Bid-ask spread trends
• Aggressive buy/sell volume correlation

High aggressive volume + collapsing depth = pre-liquidation signal.

Channel 3: Position Indicators

Track open interest and concentration hourly:

• Total notional OI vs. 24-hour volume ratio (rising ratio = speculation mode)
• Largest position size as % of available margin
• Majority-side (longs vs. shorts) unrealized P&L as % of margin

When majority P&L exceeds 80-90% of margin at extreme prices, any market shock triggers ADL.

Most builders use these dashboards reactively—alerts trigger, they respond. Advanced builders automate responses:

• Price feed down >10 seconds → auto-reduce OI caps to 50%.
• Depth collapse + high aggressive volume → auto-reduce leverage tier.
• Majority P&L >80% of margin → trigger alert, consider market halt.

From Oracle Definition to Market Stability: The Builder’s Accountability Framework

HIP-3 gave builders autonomy. It also gave them accountability.

If your market malfunctions—whether from bad oracle definition, reckless leverage, or insufficient monitoring—validators can vote to slash your 500k HYPE stake. The protocol doesn’t distinguish between malice and incompetence. It only judges outcomes: Did positions close properly? Did oracle prices anchor correctly? Was the market stable?

The path forward for builders is accountability through standardization:

1. Publish your oracle definition: Disclose exactly which data sources feed oraclePx, how frequently you update, and your fallback logic. Transparency builds trust and surfaces flaws before they crash the market.

2. Implement proof systems: For each setOracle call, generate a proof (data source inputs, calculation steps, output). Sign it and commit to a Merkle tree published on-chain hourly. This allows public auditing of your pricing decisions.

3. Monitor obsessively: Implement real-time dashboards tracking price, depth, and position health. Set up automated circuit-breakers that reduce OI caps and leverage before stress becomes crisis.

4. Design for non-24/7 assets carefully: If you’re launching stock perps, use supplemental oracle anchors (Blue Ocean ATS, CFD quotes) and asymmetric leverage (lower off-hours). Learn from trade.xyz’s December collapse.

5. Establish escalation procedures: Document when and how you invoke haltTrading. Never treat it as a casual lever—it’s your market’s emergency brake.

HIP-3’s innovation isn’t that it makes deployment frictionless. It’s that it makes deployment standardized—enabling access, operation, and accountability. Whether your market survives depends on how rigorously you implement oracle definition, monitor price feeds, and respond to early warning signals.

The $13 billion in builder-deployed volume shows the opportunity. The trade.xyz incident shows the risk. Your success depends on treating oracle definition not as a technical checkbox, but as the foundational commitment that determines whether you’re running a market or a liquidation farm.

For ongoing security support, audit preparation, and risk monitoring infrastructure implementation, consider engaging specialized firms like BlockSec who can help translate these principles into production systems. The cost of consultation is a fraction of what one well-coordinated attack could cost.