HIP-4 outcome-market data API

Pull Hyperliquid HIP-4 outcome-market data under /v1/hyperliquid/hip4/*: outcome and question discovery, side-level order books, trades, candles, and open interest. Check each data type’s history start in Venue coverage.

HIP-4 mark_price and mid_price values are implied probabilities in the [0, 1] range. Do not treat them as USD prices, and never compare them with a dollar price for BTC, ETH, or a Spot pair.

Discover an outcome first

Each outcome groups a Yes side and a No side. List outcomes 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). Pass that side coin, URL-encoded (%230), as the symbol on order-book and trade routes.
target_price and expiry define the binary; is_settled and status say whether it resolved. Re-check them 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 you start from question metadata instead of an outcome side.

Store the outcome identifier, side, and venue family with every record, so probability series can be traced later.

Request parameters

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

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

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

Response fields

Each outcome in the data array:

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

Side-level data

HIP-4 order books and trades use the same fields as the core Order books and Trades schemas (see the HIP-4 tab on each page); only the symbol form differs. Candles and Open interest carry the probability history and outcome-side positioning.

SIDE=0   # the side coin from discovery, without its leading #
curl "https://api.0xarchive.io/v1/hyperliquid/hip4/orderbook/%23$SIDE" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

A side with no stored book, such as a side whose outcome has settled, returns 404 with error_code not_found.

Live and historical HIP-4

HIP-4 live WebSocket delivery covers hip4_trades, hip4_l4_diffs, and hip4_l4_orders. hip4_orderbook and hip4_open_interest replay stored history but do not stream live; read the current book and open interest over REST. All five HIP-4 channels support historical replay: the order book, trades, and open interest use timed replay, and the two L4 channels use checkpoint-anchored bulk replay from 2026-05-02. HIP-4 has no funding or liquidation route and no candle stream; its candles are available over REST as probability-history series. Outcome-side open interest begins May 2, 2026 at roughly 10-second resolution. Pass the outcome-side coin as the symbol: WebSocket subscriptions take it as returned, such as #0, while REST routes accept 0, #0, or %230 and report #0 in meta.symbol.

// coin: a side coin from outcome discovery, such as "#0"
ws.send(JSON.stringify({ op: "subscribe", channel: "hip4_trades", symbol: coin }));

Connection and reconnect handling are in the WebSocket tab; WebSocket channels lists every family.

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). Each file keeps the outcome and side context. Build a selection in the Data Catalog; columns and coverage keys are on Export schemas.

Next step

Check a probability series for gaps before it feeds a model with Data quality.

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

HIP-4 outcome-market data API

Discover an outcome first

Request parameters

Response fields

Side-level data

Live and historical HIP-4

Export in bulk

Next step

​Discover an outcome first

​Request parameters

​Response fields

​Side-level data

​Live and historical HIP-4

​Export in bulk

​Next step

Discover an outcome first

Request parameters

Response fields

Side-level data

Live and historical HIP-4

Export in bulk

Next step