Hyperliquid HIP-4 Outcome Markets: Mechanics, API Workflow, and Verification

What HIP-4 Adds to HyperCore

HIP-4 introduces outcome markets to Hyperliquid's HyperCore. Per the Hyperliquid documentation, outcomes are fully collateralized contracts that settle within a fixed range, and HIP-4 is described as a general-purpose primitive useful for prediction markets and bounded options-like instruments. The key architectural point is that outcomes bring non-linearity and dated contracts without leverage or liquidations, and they compose with other HyperCore primitives such as portfolio margin and the HyperEVM.

The first market type is a recurring binary outcome that settles daily to the BTC mark price on HyperCore. Multi-outcome markets are documented as supported in the design but not part of the initial mainnet release, and additional features roll out in stages. Treat any specific market list, settlement source, or collateral denomination as something to confirm against current documentation and live API responses rather than assuming it from older write-ups.

• Fully collateralized: no liquidation engine involvement.
• Dated contracts: each market has an expiry and a settlement rule.
• Two-sided tokens: each outcome market has two sides, commonly Yes and No.
• Composable: designed to interact with portfolio margin and HyperEVM applications.

Assumptions and Prerequisites

This guide assumes you can reach a Hyperliquid API endpoint (the info and exchange APIs) and that you have a working HTTP client. Read-only inspection needs no key. Placing orders requires a funded account and signing, which is out of scope here beyond noting where it fits. If you are choosing an endpoint for latency-sensitive trading, the concrete provider decision belongs in RPC Assistant; see the guidance on the best Hyperliquid RPC providers for low-latency trading and the broader HyperEVM RPC provider overview.

For infrastructure planning, note that outcome trading is an API surface similar to spot with differences in asset IDs. Your integration should not assume perp-style asset IDs. The documentation points developers to the asset-ids page for the exact encoding.

The Dual-Book Mental Model

Each outcome market consists of two sides, each with a token. The tokens are labeled by sideSpecs in the outcomeMeta info endpoint, often Yes and No. The order books of the Yes and No tokens for the same outcome are merged to share liquidity. An order to buy Yes at price p is equivalent to an order to sell No at 1-p.

Under the merged book, price-time priority generalizes to price-side-time priority: for orders at the same merged price level, resting sell orders are sorted before all resting buy dual orders. Most operations abstract the dual book from the user's perspective, but the documentation notes that some ergonomics will improve in a future network upgrade. One documented example: historical orders can return primary and dual orders separately if a user sends an order that both matches and rests on the book.

Advanced users can manually split and merge outcomes to convert between primary and dual balances. For most integrations, the practical rule is to reason in merged-price space and let the API handle the dual representation, while being aware that order history may show both legs.

Settlement Math and the settleFraction

Settlement automatically converts either Yes to settleFraction quote tokens and No to 1 - settleFraction quote tokens. In particular, settleFraction = 1 for binary yes settlement and settleFraction = 0 for binary no settlement. This is the core accounting identity: the two sides always sum to one unit of the quote asset at settlement, which is what makes the contract fully collateralized.

For a bounded range or multi-outcome market, the same identity generalizes across the outcome set. When building a payout model, express every position as a fraction of the collateral unit and verify that the sum across all outcomes equals one. If your model produces a sum other than one, you have misread the market definition or the settlement source.

def payout(side: str, settle_fraction: float) -> float:
    """Return quote-token payout per unit of collateral for a binary outcome."""
    if side.lower() == "yes":
        return settle_fraction
    if side.lower() == "no":
        return 1.0 - settle_fraction
    raise ValueError(f"unknown side: {side}")

# Example: binary yes settlement
assert payout("yes", 1.0) == 1.0
assert payout("no", 1.0) == 0.0
# Example: binary no settlement
assert payout("yes", 0.0) == 0.0
assert payout("no", 0.0) == 1.0
print("settlement identity holds")

Inspecting Live Markets via the Info API

The outcomeMeta info endpoint is the source of truth for market metadata, including sideSpecs. Start every integration by fetching it and logging the raw response. Do not hardcode side labels or market identifiers; they are data, not constants. The following read-only script uses only the standard library and a placeholder endpoint.

Run it against your chosen endpoint and compare the returned market list with what the frontend shows. A mismatch usually means you are pointed at a different network or a stale cache.

import json, urllib.request

RPC_URL = "https://YOUR_HYPERLIQUID_ENDPOINT"

def post_info(payload: dict) -> dict:
    req = urllib.request.Request(
        RPC_URL,
        data=json.dumps(payload).encode(),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read().decode())

meta = post_info({"type": "outcomeMeta"})
print(json.dumps(meta, indent=2)[:2000])

# Extract side labels for each market without assuming Yes/No
for market in meta.get("universe", meta.get("markets", [])):
    sides = market.get("sideSpecs") or market.get("sides")
    print(market.get("name"), "->", sides)

Resolving Outcome Asset IDs

Outcome trading uses an API similar to spot, with key differences in asset IDs documented on the Hyperliquid asset-ids page. The practical workflow is: fetch outcome metadata, map each market and side to its asset ID, then use that ID in order and info requests. Never reuse a spot or perp asset ID for an outcome market.

The curl example below shows the request shape. Replace RPC_URL with your endpoint and adjust the payload type to match the current documentation if the info type name has changed.

curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{"type":"outcomeMeta"}' \
  | python3 -m json.tool | head -n 80

A Reproducible Verification Procedure

Use this procedure to confirm that your integration reads HIP-4 data correctly. It is deliberately read-only so it can run in CI or on a laptop without keys.

Step 1: fetch outcomeMeta and record the count of markets and the side labels. Step 2: for each market, fetch the order book or L2 book for both sides and confirm that the merged price levels are consistent with the buy-Yes-equals-sell-No identity. Step 3: pick one market near expiry and confirm the settlement rule text matches the documented source. Step 4: re-run the same script after a known interval and diff the outputs to detect schema drift.

Record results in a table like the one below. Leave the values blank until you have actually run the procedure; do not fill in estimates.

• | Check | Expected | Observed | Pass/Fail |
• | outcomeMeta returns markets | non-empty list | | |
• | side labels present | two sides per market | | |
• | merged book identity | buy Yes p ~ sell No 1-p | | |
• | settlement rule text | matches docs | | |
• | schema stable across runs | no unexpected fields | | |

Troubleshooting Common Integration Failures

Most HIP-4 integration problems fall into a few buckets. If outcomeMeta returns an empty or unexpected shape, confirm the endpoint and network first; a testnet endpoint will not show mainnet markets. If asset IDs are rejected, you are likely using a spot or perp ID where an outcome ID is required. If order history shows two entries for one order, that is the documented primary/dual split when an order both matches and rests.

If your payout model does not sum to one, re-read the market definition and the settlement source. If latency is the problem, measure it rather than guessing: time the info request from your production region and compare endpoints. The Hyperliquid performance comparison and the dedicated node options are the right places to evaluate infrastructure tradeoffs.

Limitations and Tradeoffs

HIP-4 is documented as a staged rollout. Multi-outcome markets were not part of the initial mainnet release, and some dual-book ergonomics are slated for improvement in a future network upgrade. Build your integration to tolerate schema additions and new market types rather than assuming a fixed shape.

Fully collateralized outcomes remove liquidation risk but also remove leverage; capital efficiency is different from perps. Discovery is another tradeoff: Hyperliquid's frontend is built for active traders, so if your users expect a browsing-style prediction market experience, you may need to build that layer yourself on top of the API. Finally, settlement depends on the defined source; objective, canonical sources reduce ambiguity, but you should still verify the rule for each market you trade.

Next Steps for Builders

Once read-only verification passes, the next step is a signed order flow in a test environment, followed by a monitoring layer that alerts on schema drift and settlement events. For endpoint selection, use RPC Assistant rather than embedding a provider choice in your code; see the best Hyperliquid RPC provider entry and the RPC pricing overview for capacity planning. If you operate your own infrastructure, review blockchain node hosting and the network directory before committing to a topology.

Keep a changelog of the info types you depend on, and re-run the verification procedure after any documented network upgrade. That discipline is what keeps an outcome-market integration correct as HIP-4 evolves.