> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HIP-4 outcome-market data API

> Run HIP-4 outcome-market REST routes for outcome discovery, side-level books, trades, OI, candles, and probability-priced history.

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](/venue-coverage).

<Warning>
  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.
</Warning>

## Discover an outcome first

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

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/hip4/outcomes?limit=1" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

```json theme={"theme":"github-dark"}
{
  "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](/api-reference/hip4).

## 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](/rest-api/order-books) and [Trades](/rest-api/trades) schemas (see the HIP-4 tab on each page); only the symbol form differs. [Candles](/rest-api/candles) and [Open interest](/rest-api/open-interest) carry the probability history and outcome-side positioning.

```bash theme={"theme":"github-dark"}
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`.

```javascript theme={"theme":"github-dark"}
// 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](/websocket) tab; [WebSocket channels](/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](/data-catalog); columns and coverage keys are on [Export schemas](/export-schemas).

## Next step

Check a probability series for gaps before it feeds a model with [Data quality](/data-quality).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.