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

# HIP-4 Outcome Contracts

> Binary prediction markets on Hyperliquid — symbol scheme, settlement model, and how to query them with Ironflow.

HIP-4 introduced fully-collateralized binary outcome contracts on Hyperliquid mainnet on **2026-05-02**. Each contract pays $1 to one side (the "winner") and $0 to the other, based on whether a specific real-world event occurs. Prices on either side trade between 0 and 1, representing the market's implied probability.

Ironflow indexed HIP-4 from launch — the first prediction-class fill in our database is timestamped `2026-05-02 09:00:07.983 UTC`.

## What you can query

Every HIP-4 market shows up under `source=hyperliquid` with `market_class: "prediction"`. The same data primitives (trades, fills, candles) work identically to perps and spot — only the symbol scheme is different and a few perp-only endpoints don't apply.

```bash theme={null}
# Discover the active outcome universe with full resolution metadata
curl "https://api.ironflow.sh/v1/markets?market_class=prediction" \
  -H "Authorization: Bearer if_your_api_key"
```

The response carries the full resolution definition for each market in the `metadata` field, parsed from HL's `/info outcomeMeta`:

```json theme={null}
{
  "data": [{
    "market_id": 200000,
    "market_class": "prediction",
    "display_symbol": "BTC-78213-20260503-Yes",
    "hl_coin": "#0",
    "base_asset": "HIP4-#0",
    "quote_asset": "USDC",
    "metadata": {
      "hip": "hip-4",
      "outcome_id": 0,
      "outcome_name": "Recurring",
      "side_index": 0,
      "side_name": "Yes",
      "class": "priceBinary",
      "underlying": "BTC",
      "expiry": "20260503-0600",
      "targetPrice": "78213",
      "period": "1d",
      "description": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d"
    }
  }]
}
```

## Symbol scheme

Every HIP-4 market has **two equivalent identifiers**. Pick whichever is more readable in your client — both resolve to the same underlying market.

| Form | Example | When to use |
| - | - | - |
| **Wire-form** | `#0`, `#1`, `#2`, ... | Matches HL's on-chain coin string. Stable across enrichment. Useful when comparing your data with raw HL node output. |
| **Display symbol** | `BTC-78213-20260503-Yes` | Human-readable. Composed from outcomeMeta as `{UNDERLYING}-{TARGET}-{EXPIRY-DATE}-{SIDE}` for binary price contracts. Recommended for logs and dashboards. |

For a binary outcome with two sides, the wire-form indices are flat across the entire outcome universe in registration order. Outcome 0 with two sides occupies `#0` (Yes) and `#1` (No). When HL adds outcome 1, it'll occupy `#2` and `#3`. A future 3-way outcome at outcome index 2 would occupy `#4`, `#5`, `#6`.

## The price-sums-to-1 invariant

For a binary outcome, the prices on the "Yes" and "No" sides always sum to 1.0 — that's the no-arbitrage condition. If `Yes` trades at `0.55`, the market's implied probability of the event happening is 55%, and `No` should trade at `0.45`. Persistent divergence is an arbitrage signal.

```bash theme={null}
# Compare the two sides of one outcome via the latest prints
curl "https://api.ironflow.sh/v1/trades?source=hyperliquid&market=BTC-78213-20260503-Yes&limit=1"
curl "https://api.ironflow.sh/v1/trades?source=hyperliquid&market=BTC-78213-20260503-No&limit=1"
```

The displayed wire-form coins for one binary always have prices summing to ≈1.0 (small spreads + fees + taker premium). Verifying this on every block is a cheap sanity check on your ingestion pipeline.

## What perp concepts don't apply

HIP-4 contracts are **fully collateralized** — there's no margin, no leverage, and no liquidation. The following endpoints return `400 INVALID_MARKET_CLASS` when called with a prediction symbol:

* `/v1/funding` — outcomes don't pay funding
* `/v1/open-interest` — net OI is bounded by collateral, not levered
* `/v1/mark-prices` — outcomes settle at 0 or 1, not a continuous mark

Use the multi-class endpoints instead: `/v1/trades`, `/v1/fills`, `/v1/candles`.

## Settlement events

When an outcome resolves, Hyperliquid emits a settlement event that:

1. Halts trading on both sides
2. Cancels all open orders
3. Settles every position at 0 or 1 in USDC

Ironflow tracks the settlement timestamp via the `expiry` field on `/v1/markets` metadata. Once HL begins emitting structured settlement events, those will land as a new event type — at which point this section will document the shape.

For now, `expiry` lets you build settlement-aware queries: filter `/v1/trades` to before the expiration timestamp, treat the last fill before expiry as the settlement print, and reconcile with HL's `meta` for the canonical 0/1 outcome.

## Known limitations (today)

* **Single canonical outcome at launch** — HL initially shipped one daily-rolling BTC binary (`#0` / `#1`). The pipeline auto-registers new outcomes the moment they appear in fills, so additional contracts will surface in `/v1/markets?market_class=prediction` without any code change on your side.
* **Builder-deployed outcomes** — HIP-4 follows the same two-phase pattern as HIP-3: curated canonical first, permissionless builder-deployment second. When HL opens permissionless deployment, our auto-registration uses the `outcomeMeta` flat-index scheme to assign synthetic `market_id` values in the range `200000+N`.
* **Multi-outcome contracts** — current support assumes binary (Yes/No). Markets with three or more sides will work for query/streaming but the perp-only-endpoint rejection rule (which detects `-Yes` / `-No` suffixes) won't apply automatically.

See [Sources & Markets](/concepts/sources-and-markets) for the broader symbol scheme across all market classes.


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