HIP-4 outcomes

HIP-4 outcome markets live under /v1/hyperliquid/hip4/*. Use this family when the product needs binary outcome-market data, side-level order books, trades, candles, open interest, or probability-like mark and mid values. For coverage windows and history context, start with the HIP-4 historical data API page.

HIP-4 mark_price and mid_price values are implied probabilities in the [0, 1] range. Do not treat them as USD prices.

Discover an outcome first

Each outcome groups a Yes side and a No side. List them before you pull a book or trades:

curl "https://api.0xarchive.io/v1/hyperliquid/hip4/outcomes?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

{
  "success": true,
  "data": [
    {
      "outcome_id": 0,
      "name": "Recurring",
      "class": "priceBinary",
      "underlying": "BTC",
      "expiry": "2026-05-03T06:00:00Z",
      "target_price": 78213,
      "period": "1d",
      "side_specs": [
        { "side": 0, "name": "Yes", "coin": "#0", "asset_id": 100000000, "display_title": "BTC above 78,213 on May 3 at 06:00 UTC? (Yes)" },
        { "side": 1, "name": "No", "coin": "#1", "asset_id": 100000001, "display_title": "BTC above 78,213 on May 3 at 06:00 UTC? (No)" }
      ],
      "is_settled": true,
      "status": "settled",
      "display_title": "BTC above 78,213 on May 3 at 06:00 UTC?"
    }
  ],
  "meta": { "count": 1, "next_cursor": "...", "request_id": "req_4c8a1f02e9b7d350" }
}

An outcome groups two sides: side 0 is Yes (coin #0), side 1 is No (coin #1). Use that side coin (URL-encoded, e.g. %230) for the order-book and trade routes.
target_price and expiry define the binary; is_settled and status say whether it resolved. Re-check those fields with /v1/hyperliquid/hip4/outcomes/{outcome_id} or /v1/hyperliquid/hip4/outcomes/by-slug/{slug} to see when an outcome settles.
Use /v1/hyperliquid/hip4/questions and /v1/hyperliquid/hip4/questions/{question_id} when the workflow starts from question metadata instead of an outcome side.

Request parameters

Outcome discovery (/v1/hyperliquid/hip4/outcomes):

Parameter	In	Type	Required	Description
`is_settled`	query	boolean	No	Filter by settlement; omit for both live and settled
`limit`	query	integer	No	Max results. Default 100, max 1000
`cursor`	query	string	No	Pagination cursor

The side-level order-book and trade routes take a HIP-4 coin id as {symbol} (e.g. %230 for the Yes side) plus the usual window and depth parameters. Question discovery (/v1/hyperliquid/hip4/questions) uses the same bounded-list pattern as outcomes. Use /v1/hyperliquid/hip4/questions/{question_id} for one question, and /v1/hyperliquid/hip4/outcomes/by-slug/{slug} when the public question URL slug is the identifier you have.

Response fields

Each outcome in the data array:

Field	Type	Description
`outcome_id`	integer	Numeric outcome identifier
`name`	string	Human-readable outcome name
`class`	string	Outcome class, e.g. `priceBinary`
`underlying`	string	Underlying asset for recurring price-binary outcomes
`target_price`	number	Target price for the binary
`expiry`	string	Settlement time (UTC)
`period`	string	Cadence of a recurring market, e.g. `1d`
`side_specs`	array	Per-side specs, usually side 0 (Yes) and side 1 (No)
`is_settled`	boolean	Whether the outcome has settled
`status`	string	Lifecycle status (`live`, `settled`, …)

Each side_specs entry has side (0 for Yes, 1 for No), name, coin (the #-prefixed id you pass as the symbol), and asset_id. The single-outcome route (/outcomes/{outcome_id}) also returns aggregated_oi with per-side open-interest contracts. HIP-4 order books and trades use the same fields as the core Order book and Trades schemas; only the symbol form differs, and mark_price and mid_price are implied probabilities in [0, 1], not USD.

Example

curl "https://api.0xarchive.io/v1/hyperliquid/hip4/orderbook/%230" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Use HIP-4 For

Need	Where
Outcome discovery	HIP-4 outcomes and instruments (this page)
Question lookup	HIP-4 questions and outcome by slug routes
Side-level order book	Order books, HIP-4 tab
Outcome trades	Trades, HIP-4 tab
Probability history	Candles and Open interest, HIP-4 tab

Stream it live

HIP-4 streams the side-level book and order events: hip4_orderbook, hip4_trades, hip4_open_interest, hip4_l4_diffs, and hip4_l4_orders. There is no HIP-4 funding, liquidation, or candle stream (only Lighter streams candles). Pass the outcome-side coin (URL-encoded, e.g. %230) as the symbol.

ws.send(JSON.stringify({ op: "subscribe", channel: "hip4_orderbook", symbol: "#0" }));

Connection and reconnect handling live in the WebSocket tab; see WebSocket channels for the family matrix.

Export in bulk

HIP-4 side-level data exports under the standard schemas, delivered as Parquet with ZSTD compression: l2_orderbook ($6/GB, $10 minimum), l4_orderbook ($8/GB, $25 minimum), trades ($8/GB, $15 minimum), and oi ($1/GB, $5 minimum). Preserve the outcome and side context in every file. Build a selection in the Data catalog; columns and coverage keys are on Export schemas.

HIP-4 Request Checklist

Use this checklist before HIP-4 data enters charts, models, exports, or generated clients.

Field	HIP-4 value
Namespace	`/v1/hyperliquid/hip4/*`
Identifier	Outcome ID, side identifier, or symbol from Endpoint Reference
Price handling	Treat documented mark and mid values as implied probabilities in `[0, 1]`
First probe	Outcome discovery, one order book, one trades page, or one OI request
Stop rule	Do not route outcome IDs through core Hyperliquid, Spot, HIP-3, or Lighter paths

Routing Rule

Store the outcome identifier and venue family with every record. Run outcome discovery before assuming an identifier, then pull the side-level order book, trades, candles, or open-interest route that matches the workflow. For historical analysis, combine the request with Data quality and request-ID logging so probability series can be audited later. Keep the URL encoding intact in examples such as %230, and never compare a mid_price against a dollar-denominated BTC, ETH, or Spot price.

Use Order books and Trades for the side-level routes (HIP-4 tab), Open interest for positioning, Data quality before HIP-4 data feeds a model, or Best Hyperliquid Data API for the family-selection context.

Get started

Market data

Get connected

Plans & limits

Discover an outcome first

Request parameters

Response fields

Example

Use HIP-4 For

Stream it live

Export in bulk

HIP-4 Request Checklist

Routing Rule

Next

​Discover an outcome first

​Request parameters

​Response fields

​Example

​Use HIP-4 For

​Stream it live

​Export in bulk

​HIP-4 Request Checklist

​Routing Rule

​Next

Discover an outcome first

Request parameters

Response fields

Example

Use HIP-4 For

Stream it live

Export in bulk

HIP-4 Request Checklist

Routing Rule

Next