> ## 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`](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream), [`ohlcvCandlesForToken`](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream), and [`walletTxs`](/api-reference/streaming-api/subscriptions/wallet-activity-stream) - 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. 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`**](/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. `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](/api-reference/hyperliquid-info/outcome-meta). ## 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`](/api-reference/streaming-api/types/hypercore-fill-transaction) 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`](/api-reference/hyperliquid-info/clearinghouse-state) snapshots if you need to reconcile post-settlement balances. ## Patterns ### Live probability tape Subscribe to [`ohlcvCandlesForPair`](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) 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. ## Historical depth and warehouse delivery Every HIP-4 fill is captured in the same `hl_fills` and `hl_misc_events` tables that power perp and spot history. Use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore) to land outcome trades, settlements, and USDH ledger deltas directly in ClickHouse, BigQuery, Postgres, Kafka, or S3 - no separate connector required. ### Filter to HIP-4 trades with a SQL transform The `TradesNormalizer` enriches every matched trade with an `is_hip4` boolean on the [`hl_enriched_trades`](/goldrush-pipeline-api/normalizers/hypercore#hl-enriched-trades) table. Add a [SQL transform](/goldrush-pipeline-api/sql-transforms) to keep only outcome-market rows and project the columns you care about - useful for a dedicated prediction-market warehouse without ingesting the full perp + spot firehose. ```yaml HIP-4 trades transform theme={null} transforms: hl_enriched_trades: > SELECT block_number, block_time, coin, market_name, px, sz, side, time, tid, hash, buyer_address, seller_address, usd_amount FROM hl_enriched_trades WHERE is_hip4 = true ``` Combine this with `market_type = 'prediction'` if you want to defensively guard against schema drift, or drop the predicate entirely and partition downstream tables by `market_type` to keep perp, spot, and prediction rows side by side in one pipeline. ## 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](/api-reference/hyperliquid-info/outcome-meta) - request and response schema. * [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction) - full type reference. * [OHLCV Pairs Stream](/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream) / [OHLCV Tokens Stream](/api-reference/streaming-api/subscriptions/ohlcv-tokens-stream) * [Wallet Activity Stream](/api-reference/streaming-api/subscriptions/wallet-activity-stream) * [HIP-3 markets recipe](/goldrush-hyperliquid/streaming/hip3-markets) - identical address syntax, useful for builder-deployer prefixes. * [Pipeline API HyperCore normalizers](/goldrush-pipeline-api/normalizers/hypercore) ## 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.