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

# HIP-4 Outcome Markets

> Stream prediction-market outcomes on Hyperliquid - implied-probability charts, fills, and settlement detection for HIP-4 outcome contracts using the same GoldRush WebSocket primitives that power perps and spot.

HIP-4 launched on Hyperliquid mainnet on **2 May 2026** and added a new asset class to HyperCore: **outcome markets**. Outcomes are fully-collateralized binary contracts that trade on the same CLOB as spot and perps, settle in USDH, and resolve to either `0` or `1` against an authorized oracle at expiry.

Because outcome markets ride the same matching engine as every other HyperCore market, you don't need a new client, a new WebSocket, or a new schema to stream them. Every primitive in this section - `ohlcvCandlesForPair`, `ohlcvCandlesForToken`, and `walletTxs` - works on HIP-4 markets from the moment they go live.

## HIP-4 in 60 seconds

| Property | Value |
| - | - |
| **Contract type** | Binary outcome (`Yes` / `No`), USDH-collateralized, no liquidation. |
| **Price range** | `0.001` to `0.999`. The price *is* the implied probability. |
| **Settlement** | Resolves to `0` or `1` against an authorized oracle at the resolution timestamp. PnL settles in USDH. |
| **Lifecycle** | Opening auction (\~15 min single-price clearing) → continuous CLOB trading → oracle settlement → halt + auto-settle. |
| **Fees** | Zero to open. Fees apply on close, burn, or settlement. |
| **Deployment** | Initial markets are curated and validator-deployed. Permissionless builder deployment follows in stages, mirroring HIP-3's rollout. |
| **Market encoding** | `encoding = 10 * outcome + side`. Each side of an outcome is its own tradeable market - `outcome 123, side 0` becomes encoding `1230`, `outcome 123, side 1` becomes `1231`. Use the encoding prefixed with a '#' to reference HIP-4 markets in the OHLCV endpoints. |

The first live market is a recurring **daily BTC binary outcome** that resolves against the HyperCore BTC mark price at a fixed UTC timestamp.

> [!TIP]
>
> Read the canonical spec: [HIP-4: Outcome markets](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets).

## Discover live HIP-4 markets

HIP-4 ships its own dedicated Info type, [**`outcomeMeta`**](https://goldrush.dev/docs/api-reference/hyperliquid-info/outcome-meta) - separate from `metaAndAssetCtxs` (which covers perps and spot). It returns the active outcome universe: each entry carries an integer `outcome` ID, a `name`, a structured `description`, and a `sideSpecs` array.

```bash cURL theme={null}
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "outcomeMeta"}'
```

```typescript TypeScript theme={null}
const response = await fetch("https://hypercore.goldrushdata.com/info", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ type: "outcomeMeta" }),
});

const { outcomes } = await response.json();
```

```json outcomeMeta response theme={null}
{
  "outcomes": [
    {
      "outcome": 123,
      "name": "Recurring",
      "description": "class:priceBinary|underlying:HYPE|expiry:20260310-1100|targetPrice:34.5|period:3m",
      "sideSpecs": [
        { "name": "Yes" },
        { "name": "No" }
      ]
    }
  ]
}
```

The `description` is a pipe-delimited spec. Parse it once and you get the full market definition:

| Field | Example | Meaning |
| - | - | - |
| `class` | `priceBinary` | Market class (binary outcome on a price threshold). |
| `underlying` | `HYPE` | Asset the outcome resolves against. |
| `expiry` | `20260310-1100` | Resolution timestamp, `YYYYMMDD-HHMM` UTC. |
| `targetPrice` | `34.5` | Threshold the underlying is compared against at expiry. |
| `period` | `3m` | Recurrence cadence for repeating markets. |

A typical discovery flow:

1. Call `outcomeMeta` to enumerate live `outcome` IDs and parse each `description`.
2. Compute the encoding for each side: `encoding = 10 * outcome + side`. Each side trades as its own market, so an outcome with `Yes` (side 0) and `No` (side 1) yields two encodings. Reference the market with the encoding prefixed with a '#'.
3. Subscribe to OHLCV for the encodings you want to track.
4. Stream fills via `walletTxs` for any address active on those markets.

> [!TIP]
>
> `outcomeMeta` is now available on the GoldRush drop-in Info API at `POST https://hypercore.goldrushdata.com/info`, wire-equal to upstream Hyperliquid. See the full [API reference](https://goldrush.dev/docs/api-reference/hyperliquid-info/outcome-meta.md).

## Stream live probabilities (OHLCV)

Outcome prices are bounded between `0` and `1`, so an OHLCV candle on a HIP-4 market is, by construction, a **probability candle**. Multiply by 100 for percent.

```typescript GoldRush SDK theme={null}
import {
  GoldRushClient,
  StreamingChain,
  StreamingInterval,
  StreamingTimeframe,
} from "@covalenthq/client-sdk";

const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);

client.StreamingService.subscribeToOHLCVPairs(
  {
    chain_name: StreamingChain.HYPERCORE_MAINNET,
    // HIP-4 encoding = 10 * outcome + side. Use the value(s) computed from `outcomeMeta`.
    pair_addresses: ["#1230"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (candle) => {
      const probabilityPct = (candle.close * 100).toFixed(2);
      console.log(`${candle.pair_address} implied: ${probabilityPct}%`);
    },
    error: (err) => console.error(err),
  }
);
```

```graphql GraphQL Subscription theme={null}
subscription {
  ohlcvCandlesForPair(
    chain_name: HYPERCORE_MAINNET
    pair_addresses: ["1230"]
    interval: ONE_MINUTE
    timeframe: ONE_HOUR
  ) {
    pair_address
    open
    high
    low
    close
    volume
    timestamp
  }
}
```

For a broader feed - every outcome market that references a given underlying - subscribe at the **token** level:

```typescript theme={null}
client.StreamingService.subscribeToOHLCVTokens(
  {
    chain_name: StreamingChain.HYPERCORE_MAINNET,
    token_addresses: ["BTC"],
    interval: StreamingInterval.ONE_MINUTE,
    timeframe: StreamingTimeframe.ONE_HOUR,
  },
  {
    next: (data) => console.log("BTC-referenced markets:", data),
    error: (err) => console.error(err),
  }
);
```

## Stream fills on an outcome market

Every fill on a HIP-4 market arrives as a `HypercoreFillTransaction` inside `walletTxs`. The `coin` field carries the outcome symbol, `price` is the implied probability at fill time, and `closed_pnl` realises in USDH against the `0` / `1` settlement boundary.

```typescript theme={null}
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);

const SUBSCRIPTION_QUERY = `
  subscription {
    walletTxs(
      wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"]
      chain_name: HYPERCORE_MAINNET
    ) {
      tx_hash
      block_signed_at
      from_address
      decoded_details {
        ... on HypercoreFillTransaction {
          coin
          side
          price
          size
          closed_pnl
          fee
          fee_token
          builder
          builder_fee
        }
        ... on HypercoreLedgerEvent {
          ledger_type
          time
          delta {
            ... on LedgerSpotTransfer { token amount usdc_value }
          }
        }
      }
    }
  }
`;

client.StreamingService.rawQuery(
  SUBSCRIPTION_QUERY,
  {},
  {
    next: (data) => console.log(JSON.stringify(data, null, 2)),
    error: (err) => console.error(err),
  }
);
```

## Detect settlement

When an outcome resolves, three things happen in quick succession on-chain:

1. Trading on the market halts.
2. Open orders cancel.
3. Each holder's position settles to USDH PnL against the final outcome (`0` or `1`).

Hyperliquid hasn't published a dedicated ledger-event subtype for outcome settlement, so today the reliable detection pattern is derived from the primitives that *are* exposed:

* The **last fill** on a HIP-4 market closes at price `0` or `1`.
* Followed by a **USDH ledger delta** on every position-holder's account corresponding to their settled PnL.

```typescript theme={null}
function isSettlementFill(fill) {
  return fill.price === 1 || fill.price === 0;
}
```

Combine this with periodic [`clearinghouseState`](https://goldrush.dev/docs/api-reference/hyperliquid-info/clearinghouse-state) snapshots if you need to reconcile post-settlement balances.

## Patterns

### Live probability tape

Subscribe to `ohlcvCandlesForPair` at `ONE_MINUTE` interval. Render each candle as `close * 100 %` to drive a Polymarket-style probability sparkline.

### Outcome leaderboards

Subscribe to a curated wallet list with `walletTxs`, filter `HypercoreFillTransaction` events whose `coin` matches a HIP-4 symbol, and aggregate notional (`price * size`) per wallet per market. Surface the largest open positions on each outcome.

### Settlement-PnL feed

For each position-holder on a market, capture the USDH ledger delta in the resolution window. Rank by realised PnL to produce a "biggest winners / losers on this outcome" feed every time a market resolves.

### Cross-market cohort stream

Subscribe to every active HIP-4 symbol in a single `ohlcvCandlesForPair` request. One connection, many markets - lets you build a full HIP-4 dashboard without sharding.

### "New outcomes" discovery

Once permissionless builder deployment opens, new outcomes appear in `outcomeMeta` the moment they're registered. Poll `outcomeMeta` on a short cadence and diff the `outcome` IDs against the previous snapshot; subscribe to OHLCV for any new entry. The candle stream picks up the opening auction the instant a price prints.

## Reference

* [HIP-4: Outcome markets (Hyperliquid official spec)](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets)
* [`outcomeMeta` Info API reference](https://goldrush.dev/docs/api-reference/hyperliquid-info/outcome-meta) - request and response schema.
* `HypercoreFillTransaction` - full type reference.
* OHLCV Pairs Stream / OHLCV Tokens Stream
* Wallet Activity Stream
* [HIP-3 markets recipe](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip3-markets.md) - identical address syntax, useful for builder-deployer prefixes.

## On the roadmap

* Parsed `description` fields on `outcomeMeta` (class, underlying, expiry, targetPrice, period) returned alongside the raw string.
* Multi-outcome (non-binary) market support, tracking the upstream HIP-4 rollout.


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