Prerequisites
- Python 3.10 or higher
hyperliquid-python-sdkandhttpxinstalled (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
quoteTokenfield inoutcomeMetashows.
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.
Why the standard Python SDK won’t work
The officialhyperliquid-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:
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 idoutcome and side side (only 0 and 1 are valid):
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:
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.
outcome id each day — so discover them from outcomeMeta instead of hardcoding them.
The fields on each outcome:
name—Recurringfor protocol-deployed recurring markets, ortemplate:<template name>for deployer markets.description— a pipe-separated list ofkey:valuepairs. Recurring binaries useclass:priceBinarywithunderlying,expiry(YYYYMMDD-HHMMUTC),targetPrice, andperiod. Deployer markets carry their template’s keywords instead, for exampleperp,threshold, andtime.sideSpecs— the side names, YES first.quoteToken— the token the market quotes and settles in.venueanddeployerFeeScale— present on deployer markets;venueis the deployer’s venue name.
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.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: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: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.
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 noclaim, 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:
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 pricep 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:
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 normalExchange.order(...) call:
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
TheuserOutcome exchange action converts between USDC and outcome shares directly, without trading on the book:
splitOutcome— splitXUSDC intoXYES andXNO shares of an outcome.mergeOutcome— mergeXYES andXNO shares of an outcome back intoXUSDC.mergeQuestion— mergeXYES shares from every outcome of a question intoXUSDC.negateOutcome— convertXNO shares of one outcome in a question intoXYES shares of every other outcome in that question.
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.
- Hyperliquid methods — full method availability matrix.
- outcomeMeta API reference — request and response schema.
- settledOutcome API reference — the result of a settled outcome.
- userOutcome API reference — split, merge, and negate actions.
- Hyperliquid order precision —
szDecimalsand price tick rules that apply to outcome orders too. - Hyperliquid signing overview — required for every
Exchange.*call.