# 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.

## 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.

- Live: a $10,000 long opened against the pool. (https://fabrknt.com/recipes/hip3-launch/trade.jpg)
- 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. (https://fabrknt.com/recipes/hip3-launch/paused.jpg)

## Run it (~24 min)

### 1. Run a newly listed market on your machine (~10 min)

```bash
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. Trade on it, then feed it a bad price (~3 min)

```bash
./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. Watch a pushed book get refused (~1 min)

```bash
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. Put the check in your own contract (~5 min)

```bash
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`:

```solidity
// 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. Run your market's oracle (dry run) (~5 min)

```bash
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)

- 2026-10-10: A wallet spent $130,873 pushing ETH's book on Hyperliquid. Papertrade, an exchange that settled at Hyperliquid's mid, paid it $1.41M ($1.28M net). We replayed the same 228 positions: settling at the oracle instead cut what they took by only 15%. (https://github.com/fabrknt/hl-price-guard/tree/main/cases/papertrade-20261010)
- 2026-07-27: A HIP-3 deployer's oracle for xyz:SKHX fell 15.6% in one update, then kept stepping down 1% at a time. A check that only compares each read with the previous one let 39 prices under $1,000 through. A jump latch let none through. (https://github.com/fabrknt/hl-price-guard/tree/main/cases/skhx-20260727)

## Put together: the parts

### 1. Keep a thin book tradable from day one: Day One

https://github.com/fabrknt/dayone

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.

```bash
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

https://github.com/fabrknt/hl-price-guard

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.

```bash
forge install fabrknt/hl-price-guard@v0.4.1
echo 'hl-price-guard/=lib/hl-price-guard/src/' >> remappings.txt
```

```solidity
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

https://github.com/fabrknt/hip3-ops

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.

```bash
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](https://fabrknt.com/hip3/learn/how-perpetual-dexs-work/index.html): Perps, funding, margin and liquidation.
2. [Hyperliquid Architecture, lessons 3, 4, 6, 7](https://fabrknt.com/hip3/learn/hyperliquid-architecture/index.html): 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](https://fabrknt.com/hip3/course/index.html): What an operator takes on, settlement currency and economics, running the oracle, risk limits, keys and how to stop.
4. [HyperEVM Development, lesson 4](https://fabrknt.com/hip3/learn/hyperevm-development/04-l1-precompiles.html): If you also build on HyperEVM: reading HyperCore prices from a contract through the precompiles.

## Before real money

- Replay the two incidents against your own bounds and cap (hl-price-guard cases/ and docs/safe-limits.md). (https://github.com/fabrknt/hl-price-guard/tree/main/cases)
- Run Day One's end-to-end demo after every change to the pool or the keeper (npm run demo).
- After launch, compare what your market's operator actions were with public data in HIP-3 Record. (https://fabrknt.com/hip3/record/index.html)
- Day One and HL Price Guard aren't audited. Day One runs on HyperEVM testnet only, and we don't offer it to traders.
- HIP-3 Ops isn't audited and only sends to testnet. Its RedStone path hasn't been run with a real API key yet.
- The per-minute cap sizes are first estimates from one incident (hl-price-guard docs/safe-limits.md). They aren't bounds.

## 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 and not affiliated with Hyperliquid. The parts are unaudited.
