HIP-3 Protocol

HIP-3 is Hyperliquid's protocol for deploying custom perpetual contracts with external oracle prices. This page explains how Rubicon uses HIP-3.

What is HIP-3?

HIP-3 allows anyone to deploy perpetual futures on Hyperliquid with custom oracle feeds.

Native Perps vs HIP-3 Perps

Aspect	Native Perps (BTC, ETH)	HIP-3 Perps (Rubicon)
Oracle	Validator consensus	Deployer-provided
Price source	CEX weighted median	Custom (we use Polygon/Yahoo)
Deployment	Hyperliquid team	Anyone
Trust model	Decentralized validators	Deployer reputation

How It Works

1. Asset Registration

Deploy a new perpetual via registerAsset2():

const registerAction = {
  type: "registerAsset2",
  asset: {
    name: "SOXX",
    szDecimals: 2,
    maxLeverage: 10,
    // ... other parameters
  }
};

This creates a new tradeable market on Hyperliquid.

2. Oracle Submission

Publish prices every 3 seconds via setOracle():

const oracleAction = {
  type: "setOracle",
  dex: "ETF",
  oraclePxs: {
    "SOXX": "225.00"
  },
  markPxs: [{
    "SOXX": "224.95"
  }],
  externalPerpPxs: {
    "SOXX": "225.00"
  }
};

3. Price Processing

Hyperliquid processes our submission:

Our Oracle Price
      │
      ├──► Used for liquidations
      ├──► Used for funding calculation
      │
Our Mark Suggestion ──┐
                      ├──► Hyperliquid calculates final mark
HL Internal Mark ─────┘

Oracle Submission Format

Every 3 seconds, we submit:

{
  "dex": "ETF",
  "oraclePxs": {
    "SOXX": "225.00",
    "KODEX": "45000.00"
  },
  "markPxs": [{
    "SOXX": "224.95",
    "KODEX": "44995.00"
  }],
  "externalPerpPxs": {
    "SOXX": "225.00",
    "KODEX": "45000.00"
  }
}

Field Descriptions

Field	Description	Used For
dex	Identifier for our deployment	Routing
oraclePxs	Authoritative ETF prices	Liquidations, funding
markPxs	EMA-smoothed suggestions	Mark price input
externalPerpPxs	Circuit breaker reference	Price band validation

Price Types Explained

Oracle Price (oraclePxs)

The authoritative price from our data source.

Source: Polygon/Yahoo → ETF price
Usage: Liquidations, funding rate calculation
Updates: Every 3 seconds during market hours
Frozen: During market closure

Mark Price Suggestion (markPxs)

Our EMA-smoothed price suggestion.

Source: EMA of oracle prices
Purpose: Smooth display, reduce manipulation
Processing: HL takes median with internal mark
Result: Final mark price shown to users

External Perp Price (externalPerpPxs)

Reference price for circuit breakers.

Source: Same as oracle (for ETFs)
Purpose: Validate mark isn't too far from reference
Constraint: Mark bounded within ±(1/max_leverage)

Signing Requirements

Oracle submissions must be signed by the deployer wallet:

import { ethers } from "ethers";

const wallet = new ethers.Wallet(ORACLE_PRIVATE_KEY);

async function submitOracle(prices) {
  const action = {
    type: "setOracle",
    dex: "ETF",
    oraclePxs: prices.oracle,
    markPxs: [prices.mark],
    externalPerpPxs: prices.external
  };

  const timestamp = Date.now();
  const message = JSON.stringify({ action, timestamp });
  const signature = await wallet.signMessage(message);

  const response = await fetch("https://api.hyperliquid.xyz/exchange", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      action,
      signature,
      timestamp
    })
  });

  return response.json();
}

Oracle Loop Implementation

class OracleSystem {
  constructor() {
    this.interval = 3000;  // 3 seconds
    this.running = false;
  }

  async start() {
    this.running = true;
    while (this.running) {
      try {
        await this.submitCycle();
      } catch (error) {
        console.error("Oracle cycle failed:", error);
      }
      await this.sleep(this.interval);
    }
  }

  async submitCycle() {
    // 1. Fetch prices from sources
    const prices = await this.fetchPrices();

    // 2. Validate prices
    this.validatePrices(prices);

    // 3. Calculate EMA for mark suggestion
    const ema = this.calculateEMA(prices);

    // 4. Submit to Hyperliquid
    await this.submit({
      oracle: prices,
      mark: ema,
      external: prices
    });

    // 5. Persist state
    await this.saveState();
  }

  stop() {
    this.running = false;
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

Error Handling

Submission Errors

Error	Cause	Response
Invalid signature	Wrong key	Check wallet
Rate limited	Too many requests	Slow down
Price too stale	Old timestamp	Use current time
Price out of bounds	Too different from last	Validate before submit

Recovery

async function submitWithRetry(prices, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await submitOracle(prices);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(1000 * (i + 1));  // Exponential backoff
    }
  }
}

Trust Model

Who to Trust

Traders trust that:

1. Our oracle publishes accurate ETF prices

2. We don't manipulate prices for profit

3. Our infrastructure is reliable

How We Build Trust

1. Transparency — Open documentation of methodology

2. Verifiability — Prices match public ETF data

3. Reliability — Consistent uptime and updates

4. Reputation — Track record over time

Comparison with Other Oracles

Oracle	Trust Model	Speed	Coverage
Rubicon HIP-3	Deployer	3s	ETFs
Chainlink	Decentralized nodes	~1min	Crypto, some equities
Pyth	First-party publishers	~400ms	Crypto, FX, equities
HL Validators	Validator consensus	3s	Major crypto

Resources

• Hyperliquid Docs

• HIP-3 Specification

• Our Oracle Code — Implementation details