Raviole Labs
Raviole Labs

HIP-4 read paths: what the mainnet API actually returns

We probed Hyperliquid HIP-4 outcome markets on mainnet: coin encodings, asset ids, settlement fills and the builder-code path, with what the API really returns.

hyperliquidhip-4apiprediction-marketsbuilders

HIP-4 is Hyperliquid’s native outcome-market standard, and the docs will give you the concepts. What they will not give you is the exact shape of what comes back over the wire. We probed mainnet while building our terminal and wrote everything down. This post is the field notes, verified against live data in August 2026.

The catalog: outcomeMeta

The market catalog comes from the standard info endpoint:

POST /info
{ "type": "outcomeMeta" }

The interesting part is that each market’s description field is not prose, it is a structured string you can parse:

class:priceBinary|underlying:BTC|expiry:20260817-0600|targetPrice:63035|period:1d

Split on |, then on :, and you have a typed catalog: market class, underlying, expiry timestamp, target price, period. No scraping, no guessing from titles.

Coins, sides, and the 100 million offset

Each side of an outcome market trades as its own spot coin, named #<outcomeId><side> where side 0 is YES and side 1 is NO. Your balances show up in spotClearinghouseState as rows prefixed with +, and here is the trap that costs an afternoon:

asset id = 100_000_000 + encoding

If you take the encoding from the balance row and use it directly as the asset id in an order, nothing works. Add the hundred-million offset and everything works. That single line is probably worth this whole post.

The read paths you already know still work

The good news for anyone who has built against Hyperliquid before:

  • allMids includes all the # coins, over both REST and WebSocket.
  • l2Book, recentTrades, and candleSnapshot accept them like any other coin, so books, tapes, and candles come free.
  • The WebSocket trades feed includes both wallet addresses on each trade. For outcome markets that is a gift: you can watch which wallets are building YES positions in size, in real time.

Settlement leaves fingerprints

Resolution does not arrive as a special event. It arrives in userFills, as fills with dir: "Settlement" at a price of 1.0 for the winning side and 0.0 for the loser. Before resolution, redeeming a matched YES/NO pair shows up as dir: "Merge Outcome" at 0.5 and 0.5.

If your accounting treats fills as the source of truth, settlement just flows through it. If it does not, this is your reason to refactor.

The builder-code path

Orders take the usual action shape, plus an optional builder field:

{ "a": assetId, "b": isBuy, "p": price, "s": size, "r": reduceOnly, "t": type }

with builder: { "b": address, "f": fee } where the fee is expressed in tenths of a basis point. This is the whole monetization story for a front-end: route orders, collect the builder fee, hold no funds, touch no keys. And a detail that matters for anyone weighing this: the 500k HYPE stake requirement applies to market deployers, not to front-ends. Anyone can build the interface.

Why we care

We are building Verdict on top of these read paths: every outcome market on Hyperliquid, in one terminal, a React front over a read-only data plane. No custody, no keys, paid by the builder code. If you are a chain team or a builder poking at HIP-4 and these notes saved you a day, that is the kind of day we sell back at the studio.