Skip to content
← Market recipes

Open a HIP-3 perp market

Open a HIP-3 perp market on Hyperliquid that stays tradable on a thin first day. Then guard whatever settles on its prices against a pushed book or a jumping oracle. You get what to read, which parts to combine, and what to check.

Run it now (about 24 min) ↓For AI agents, the same recipe as Markdown: /llms/recipes/hip3-launch.md

What you end up with

Here's where you end up: a HIP-3 perp market you can trade from a web page, a pool that takes the other side while the book is thin, and a price check that pauses everything when the oracle jumps. Below is our own run. We opened a $10,000 long, then fed in a bad price.

HyperCoreHIP-3 market: book + oracleHIP-3 Ops: oracle · config · keysprices via precompilesHyperEVMHL Price Guarddeviation · jump latch · per-minute capDay One pooltakes the other side while the book is thinkeeper: settle · liquidatetraders · web page
Live: a $10,000 long opened against the pool.
Live: a $10,000 long opened against the pool.
We fed in a 15% oracle drop: "Paused: the oracle jumped too far since the last accepted price (1501 bp, limit 200)". Nothing settles at that price.
We fed in a 15% oracle drop: "Paused: the oracle jumped too far since the last accepted price (1501 bp, limit 200)". Nothing settles at that price.

Run it (24 min)

  1. 1

    Run a newly listed market on your machine

    10 min
    git clone --recurse-submodules https://github.com/fabrknt/dayone
    cd dayone && npm install
    npm run demo

    You will see

    …
    ok   short settled without a request
    …
    ok   cleared on a one-sided book
    all ok

    A local chain with Hyperliquid's price precompiles mocked, a funded pool and its keeper. The demo walks through opens, settles, a liquidation, the jump latch, trading hours, a halted market and an operator ending the market, checking each step. No keys, no funds.

  2. 2

    Trade on it, then feed it a bad price

    3 min
    ./keeper/dev.sh                      # chain, pool, keeper, a moving price
    cd web && npm install && npm run dev # 2nd terminal, from dayone/; open the URL
    echo 0.85 > /tmp/dayone-shock        # after opening a position: a 15% drop

    You will see

    Paused: the oracle jumped too far since the last accepted price (1501 bp, limit 200)
    keeper: liquidate(1) skipped: Breach Jump: 1501 over 200

    The page's dev wallet trades against the pool. The last line replays an SK Hynix-style bad update. The jump latch refuses that price, so nothing settles or gets liquidated at it.

  3. 3

    Watch a pushed book get refused

    1 min
    cd ~   # a fresh folder, not inside dayone
    git clone --recurse-submodules https://github.com/fabrknt/hl-price-guard
    cd hl-price-guard && forge test --match-contract Quickstart -vv

    You will see

    normal book:   accepted at $2427.23
    pushed book:   rejected, mid vs oracle 20 bp, limit 15

    The second book is pushed 20 bp away from the oracle, the way Papertrade's was. The price check refuses it.

  4. 4

    Put the check in your own contract

    5 min
    cd ~
    forge init mymarket && cd mymarket
    forge install fabrknt/hl-price-guard@v0.4.1
    echo 'hl-price-guard/=lib/hl-price-guard/src/' >> remappings.txt
    # save src/MyMarket.sol (MyMarket, under "Put together") and test/MyMarket.t.sol (below), then:
    forge test --match-test test_pushedBook

    test/MyMarket.t.sol

    // SPDX-License-Identifier: Apache-2.0
    pragma solidity ^0.8.24;
    import {HLTest} from "hl-price-guard/test/HLTest.sol";
    import {HLPriceGuard} from "hl-price-guard/HLPriceGuard.sol";
    import {MyMarket} from "../src/MyMarket.sol";
    
    contract MyMarketTest is HLTest {
        function setUp() public { installHL(); }
    
        function test_pushedBook() public {
            MyMarket m = new MyMarket();
            setBook(ETH, 2427.23e18, 2428.00e18, 2432.00e18, 2432.10e18);
            vm.expectRevert(
                abi.encodeWithSelector(HLPriceGuard.PriceRejected.selector, HLPriceGuard.Breach.MidOracle, 20, 15)
            );
            m.price();
        }
    }

    You will see

    [PASS] test_pushedBook()

    Your contract now reads Hyperliquid's oracle through the guard. On a pushed book, it reverts with PriceRejected.

  5. 5

    Run your market's oracle (dry run)

    5 min
    cd ~   # needs Rust (cargo)
    git clone https://github.com/fabrknt/hip3-ops && cd hip3-ops
    cargo build --release
    ./target/release/hip3-ops oracle examples/oracle-testnet.toml --ticks 3

    You will see

    oracle hopsa | 2 asset(s) | every 3000 ms | dry run
    1794637678523 hopsa:AAPL=355.62 hopsa:BTC=67334
    …

    Now the operator's side. hip3-ops reads live prices from its sources and works out the oracle update for each asset of a testnet dex, every 3 seconds. It doesn't send anything. The same tool also plans config changes, signs through a multisig, and records receipts anyone can recompute.

Why: what went wrong (measured)

Put together: the parts

1. Keep a thin book tradable from day one: Day One (opens in a new tab)

A loss-funded counterparty pool for a newly listed HIP-3 perp. It comes with guarded oracle settlement (HL Price Guard), per-minute caps, exits for a halted market, a keeper and a web UI. The demo runs on your machine with no keys (you need Foundry, Node 24, Python 3 and zsh; about ten minutes). Unaudited, testnet only.

git clone --recurse-submodules https://github.com/fabrknt/dayone
cd dayone && npm install && npm run demo

2. Settle a HyperEVM contract on Hyperliquid prices without being pushed: HL Price Guard (opens in a new tab)

read refuses a book or mark that has drifted from the oracle. If a push moves the oracle too, you also need an independent reference, the jump latch (HLPriceGuard.observe) and a per-minute cap (ExposureBudget.Rolling). Per-asset bounds are in docs/safe-limits.md. Pin a tag. Unaudited.

forge install fabrknt/hl-price-guard@v0.4.1
echo 'hl-price-guard/=lib/hl-price-guard/src/' >> remappings.txt
import {HLPriceGuard} from "hl-price-guard/HLPriceGuard.sol";

contract MyMarket {
    HLPriceGuard.Asset ETH = HLPriceGuard.Asset({dex: 0, index: 1, szDecimals: 4});
    HLPriceGuard.Bounds BOUNDS =
        HLPriceGuard.Bounds({maxMarkOracleBps: 15, maxMidOracleBps: 15, maxSpreadBps: 10, maxRefOracleBps: 0});

    function price() public view returns (uint256) {
        // The oracle (1e18), or a revert PriceRejected(reason, observedBps, limitBps).
        return HLPriceGuard.read(ETH, BOUNDS, HLPriceGuard.Ref(0, 0, 0));
    }
}

3. Run the oracle, the market config and the keys: HIP-3 Ops (opens in a new tab)

Self-hosted and non-custodial, in Rust. It has an oracle with failover and market hours, plan/apply for the market config, a native multisig, a policy-checked signer, oracle receipts you can recompute, a risk scorecard, and shadow monitoring of any operator from public data. The operator runs it with their own keys, and sending is testnet-only. RedStone sources need an API key (HIP3_OPS_REDSTONE_API_KEY). Unaudited; AGPL-3.0.

git clone https://github.com/fabrknt/hip3-ops && cd hip3-ops
cargo build --release
./target/release/hip3-ops doctor --all                      # read-only, mainnet
./target/release/hip3-ops plan examples/paragon-sample.toml # read-only diff against a live dex

Go deeper, in order

  1. How Perpetual DEXs Work, lessons 1–3: Perps, funding, margin and liquidation.
  2. Hyperliquid Architecture, lessons 3, 4, 6, 7: The on-chain book, HyperCore vs HyperEVM, the liquidation engine, and HIP-1 to HIP-3.
  3. Running a HIP-3 Market, lessons 1–5: What an operator takes on, settlement currency and economics, running the oracle, risk limits, keys and how to stop.
  4. HyperEVM Development, lesson 4: If you also build on HyperEVM: reading HyperCore prices from a contract through the precompiles.

Before real money

Run end to end

2026-11-14 We followed it in a clean environment. A fresh clone of fabrknt/dayone: npm run demo (all ok) and forge test (70 passed) on hl-price-guard v0.4.1. keeper/dev.sh and the web page: a $10,000 long opened, then the 0.85 shock (paused, liquidation skipped; the screenshots above). hl-price-guard's Quickstart (accepted and rejected, as shown). A fresh clone of fabrknt/hip3-ops: cargo test (186 passed) and the oracle dry run shown. A fresh Foundry project: forge install of v0.4.1, and the MyMarket contract and test above (passed, forge 1.7.1).

Fabrknt is independent. We're not affiliated with Hyperliquid. The parts aren't audited.