HIP-4 outcome-market data API

HIP-4 outcome markets live under /v1/hyperliquid/hip4/*. Use this family when the workflow needs binary outcome-market data, side-level order books, trades, candles, open interest, or probability-like mark and mid values. Check Venue coverage for the family and coverage window.

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, "request_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd" }
}

This representative response omits meta.next_cursor; paginate only with the cursor returned by the actual response.

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

Side-level order-book routes use a HIP-4 coin id as {symbol} (for example %230 for the Yes side). Snapshot requests use timestamp and optional depth (maximum 20). History requests use start, end, cursor, limit (default 100, maximum 1000), and optional depth (maximum 20). Trade routes use their own start, end, cursor, and limit (default 100, maximum 1000) parameters and do not take depth. 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

Live and historical HIP-4

Live HIP-4 WebSocket channels are hip4_trades, hip4_l4_diffs, and hip4_l4_orders. Stored hip4_orderbook and hip4_open_interest history remains replayable; use REST for current order-book and open-interest reads. Stored hip4_trades data can also be replayed; the live hip4_orderbook and hip4_open_interest bridges are paused. HIP-4 has no funding or liquidation route and no dedicated candle stream; its candles are available over REST as probability-history series. Outcome-side OI begins May 2, 2026 at roughly 10-second resolution. Pass the outcome-side coin (URL-encoded, e.g. %230) as the symbol.

ws.send(JSON.stringify({ op: "subscribe", channel: "hip4_trades", 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 ($3/GB, $5 minimum), l4_orderbook ($4/GB, $12.50 minimum), trades ($4/GB, $7.50 minimum), and oi ($0.50/GB, $2.50 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, or Data quality before HIP-4 data feeds a model.

Start

API

Exports

Data types

Venues

Data rights

HIP-4 outcome-market data API

Discover an outcome first

Request parameters

Response fields

Example

Use HIP-4 for

Live and historical HIP-4

Export in bulk

HIP-4 request checklist

Routing rule

Next

​Discover an outcome first

​Request parameters

​Response fields

​Example

​Use HIP-4 for

​Live and historical HIP-4

​Export in bulk

​HIP-4 request checklist

​Routing rule

​Next

Discover an outcome first

Request parameters

Response fields

Example

Use HIP-4 for

Live and historical HIP-4

Export in bulk

HIP-4 request checklist

Routing rule

Next