Skip to main content
HIP-4 introduces outcome markets to Hyperliquid — fully collateralized binary contracts that settle within a fixed range. They are a general-purpose primitive for prediction markets and bounded options-like instruments. HIP-4 launched on mainnet on May 2, 2026 with a recurring BTC daily binary. Mainnet now also lists recurring markets on other assets and markets that third-party deployers create from validator-approved templates.
Prerequisites
  • Python 3.10 or higher
  • hyperliquid-python-sdk and httpx installed (pip install hyperliquid-python-sdk httpx)
  • Reliable Hyperliquid RPC endpoint (sign up for free)
  • A funded testnet or mainnet wallet with USDC — outcome markets quote and settle in USDC, as the quoteToken field in outcomeMeta shows.

What HIP-4 outcome markets are

An outcome market is a fully collateralized binary contract priced as a probability between 0 and 1. At expiry, the contract settles to either YES (1) or NO (0) based on a deterministic rule. Each side is held as a native HyperCore asset — there are no ERC-20 wrappers, no Gnosis Conditional Tokens, and no separate matching layer. Outcomes share the matching engine, account model, and API surface with spot and perpetuals. Once you handle the asset encoding correctly, every existing tool works — order placement, cancels, modifies, fills, the websocket. There is no leverage and no liquidation. Positions are fully collateralized at open. Mainnet lists two kinds of outcome markets:
  • Recurring markets — the protocol deploys and settles them on a fixed cadence. They include daily binaries on BTC, ETH, SOL, and HYPE that settle at 06:00 UTC against the HyperCore mark price, and a daily BTC price-bucket question.
  • Deployer markets — HIP-4 deployers create them from templates that validators vote on, such as price targets, sports results, company events, and policy-rate decisions. Each deployer publishes under its own venue name.
A question groups several outcomes, of which exactly one settles to YES and all others settle to NO.

Why the standard Python SDK won’t work

The official hyperliquid-python-sdk (v0.24.0, the latest release) does not know about HIP-4. The Info client builds its coin_to_asset map from spot_meta only — outcome encodings starting at 100_000_000 are unknown to the resolver. A naive call fails:
The fix is small but necessary: fetch outcomeMeta, compute the asset id and coin string for every live outcome, and inject those entries into the SDK’s resolver maps. After that, Exchange.order(coin="#10", ...) and Info.l2_snapshot("#10") work as if HIP-4 were a native concept.

Asset ID encoding

Outcomes share most implementation details with spot, but the API representation is different. The encoding is the single biggest source of bugs for new HIP-4 integrators. For an outcome with id outcome and side side (only 0 and 1 are valid):
Side 0 is YES and side 1 is NO, matching the order of sideSpecs in outcomeMeta. The same encoding integer is used in three different string forms, each in a different context:
Two coin strings exist for the same side asset. The # form is what /info l2Book and Exchange.order(...) expect. The + form is what spotClearinghouseState returns under your account balances. Mixing them up will silently fail to find your position — l2Book with +10 returns nothing, balance lookup with #10 returns nothing.
A small encoding helper:

Discovering markets with outcomeMeta

The outcomeMeta info request returns all live outcomes and questions. Point HIP-4 trading code at the official Hyperliquid public API — https://api.hyperliquid.xyz (mainnet) or https://api.hyperliquid-testnet.xyz (testnet) — which serves every method this guide uses, including l2Book and the /exchange actions that Chainstack-hosted endpoints do not serve. For HyperEVM operations and the /info methods your node supports, including outcomeMeta and settledOutcome, use your Chainstack endpoint. See Hyperliquid methods for the full availability matrix.
A mainnet response, with each array shortened to one or two entries — a recurring BTC daily binary, a deployer market, and the recurring BTC price-bucket question:
Outcome and question IDs change with every recurring instance — a new BTC daily binary gets a new outcome id each day — so discover them from outcomeMeta instead of hardcoding them. The fields on each outcome:
  • name — Recurring for protocol-deployed recurring markets, or template:<template name> for deployer markets.
  • description — a pipe-separated list of key:value pairs. Recurring binaries use class:priceBinary with underlying, expiry (YYYYMMDD-HHMM UTC), targetPrice, and period. Deployer markets carry their template’s keywords instead, for example perp, threshold, and time.
  • sideSpecs — the side names, YES first.
  • quoteToken — the token the market quotes and settles in.
  • venue and deployerFeeScale — present on deployer markets; venue is the deployer’s venue name.
Questions carry namedOutcomes (the outcomes that can settle to YES), a fallbackOutcome, and settledNamedOutcomes. The recurring BTC price-bucket question uses class:priceBucket with two priceThresholds. The top-level deployers array lists each deployer with its venue and sub-deployers.
outcomeMeta does not return the per-side coin strings or asset ids. You compute them client-side from outcome and side using the asset ID encoding formula.
A short parser for the recurring-binary description format, and a helper that finds the current instance of a recurring daily binary:

Patching the SDK

Once you have the live outcomes, inject them into the SDK’s resolver maps so the existing client methods accept HIP-4 coin strings:
The if coin in info.coin_to_asset: continue guard is defensive: if a future SDK release adds native HIP-4 support, the patch becomes a no-op rather than producing duplicate entries. Pin a tested SDK version in your requirements.txt regardless.

Settlement mechanics

Recurring outcomes are auto-deployed and auto-settled by the protocol on a fixed cadence. The settlement rule for binary price-based outcomes:
Where markPrice0 and markPrice1 are the two HyperCore mark-price updates immediately before and after settlementTime, and t0, t1 are their timestamps. The protocol takes those two flanking samples, linearly interpolates between them at the exact settlement timestamp, and compares the interpolated value to the target. The recurring price-bucket question uses the same interpolated price to pick one of three buckets — below the first threshold, between the two thresholds, or at or above the second — and the matching named outcome settles to YES.
The samples are mark-price updates, not candle OHLCV closes, not oracle snapshots, and not a TWAP. If you implement pre-expiry position management against candle data, your settlement estimate will diverge from the actual settled value, especially in fast-moving markets where mark updates are dense around the settlement timestamp.
For very fast-moving markets the choice of t0 and t1 updates can move the settled price by several ticks compared to the visible mark price at the exact timestamp. Deployer markets settle according to their template — for example, a template:binaryPrice market names its price source in priceDescription.

Holding to settlement

Settlement is automatic. There is no claim, redeem, or settle call. At expiry, YES converts to settleFraction USDC per share and NO to 1 - settleFraction USDC per share — 1 and 0 for a binary YES result — and the outcome is removed from the next outcomeMeta response. To read the result of a settled outcome, query settledOutcome, which returns the outcome spec, its settleFraction, and the settlement details such as the settled price. To watch a position through settlement, poll spotClearinghouseState for the +<encoding> balance until it disappears, or compare your USDC balance before and after the expiry timestamp:
If a reader expects a Polymarket or Gnosis CTF flow with a redeemPositions call, they will wait for a transaction that never comes — settlement happens inside the matching engine. To exit before expiry, sell your shares on the book, or merge matching YES and NO shares back into USDC.

Reading the order book

The YES and NO books of an outcome are merged into one book that shares liquidity: buying YES at price p is the same order as selling NO at 1 - p. l2Book returns the merged book from the side you ask for, so the NO book is the YES book mirrored around 1:
On the BTC daily book, a YES bid of 0.48543 for 87 shares appears as a NO ask of 0.51457 for the same 87 shares. Use the #<encoding> form for l2Book and websocket subscriptions, never the +<encoding> balance form.

Placing an order

Once the SDK is patched, order placement is a normal Exchange.order(...) call:
Outcome orders follow these rules: Validate the price and integer size client-side before signing the order — the round-trip to discover an invalid value via server rejection is wasteful in latency-sensitive code. To bet against an outcome, buy its NO side. On the merged book, buying NO at price q is the same order as selling YES at 1 - q.

Fees, mint, normal trade, and burn

Outcome trading only charges fees when closing or settling, not when opening. Buys that open or add to a position pay no fee; sells that close a position and merges pay the fee, in USDC. Only fee-paying volume counts toward your volume. The matching engine classifies every fill into one of six cases: Fee rates follow your spot fee tier, returned by userFees as userSpotCrossRate (taker) and userSpotAddRate (maker), after any referral discount. Deployer markets with a deployerFeeScale of 1.0 charge twice that rate: at a userSpotCrossRate of 0.0006 and a 4% referral discount, a taker sell pays 2 * 0.0006 * 0.96 = 0.001152 of px * sz. Outcome trading has no maker rebates — users who would otherwise receive rebates pay zero on maker orders instead. Mint and burn happen implicitly inside the matching engine as a side effect of the fill — you cannot request them through an order.

Splitting, merging, and negating outcomes

The userOutcome exchange action converts between USDC and outcome shares directly, without trading on the book:
  • splitOutcome — split X USDC into X YES and X NO shares of an outcome.
  • mergeOutcome — merge X YES and X NO shares of an outcome back into X USDC.
  • mergeQuestion — merge X YES shares from every outcome of a question into X USDC.
  • negateOutcome — convert X NO shares of one outcome in a question into X YES shares of every other outcome in that question.
Because exactly one outcome of a question settles to YES, mergeQuestion and negateOutcome let holders of a full set redeem USDC before the outcomes settle. The hyperliquid-python-sdk has no helper for userOutcome; sign it as an L1 action. See the userOutcome reference for request examples.

Where to go next

Worked-out reference implementation with progressive examples and a market-maker bot:
  • chainstacklabs/hyperliquid-hip-4 — Python scripts for market discovery, questions, account state, order book snapshots, the websocket feed, the order lifecycle, categorical trades, split and merge, a settlement watcher, and a passive market-maker.
Related reference and guides on Chainstack: Upstream documentation:
Last modified on November 12, 2026