Skip to main content

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

PropertyValue
Contract typeBinary outcome (Yes / No), USDH-collateralized, no liquidation.
Price range0.001 to 0.999. The price is the implied probability.
SettlementResolves to 0 or 1 against an authorized oracle at the resolution timestamp. PnL settles in USDH.
LifecycleOpening auction (~15 min single-price clearing) → continuous CLOB trading → oracle settlement → halt + auto-settle.
FeesZero to open. Fees apply on close, burn, or settlement.
DeploymentInitial markets are curated and validator-deployed. Permissionless builder deployment follows in stages, mirroring HIP-3’s rollout.
Market encodingencoding = 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.

​
Discover live HIP-4 markets

HIP-4 ships its own dedicated Info type, outcomeMeta - 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. 
curl -X POST https://hypercore.goldrushdata.com/info \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "outcomeMeta"}'
outcomeMeta response
{
  "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:
FieldExampleMeaning
classpriceBinaryMarket class (binary outcome on a price threshold).
underlyingHYPEAsset the outcome resolves against.
expiry20260310-1100Resolution timestamp, YYYYMMDD-HHMM UTC.
targetPrice34.5Threshold the underlying is compared against at expiry.
period3mRecurrence 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.

​
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. 
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),
  }
);
For a broader feed - every outcome market that references a given underlying - subscribe at the token level: 
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. 
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.
function isSettlementFill(fill) {
  return fill.price === 1 || fill.price === 0;
}
Combine this with periodic clearinghouseState 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.

​
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 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 table. Add a SQL transform 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.
HIP-4 trades transform
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

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