Skip to main content
HIP-4 introduced outcome contracts to Hyperliquid — prediction-market style side tokens that settle to 0 or 1 based on a real-world question. Each question has two or more outcomes, and each outcome has one side token per side (YES / NO). Coinversa indexes the full HIP-4 wire format and exposes discovery, settlement, volume, recent trades, trader overlap, and perp-position context for every outcome.
HIP-4 mainnet launched 2026-05-02. Queries with a since reaching earlier are clamped to that date.

​
Encoding

The HIP-4 wire format uses an integer encoding that combines outcome ID and side:
side is the side index from the outcome’s metadata (sides[].name): side 0 is the first side, which the API treats as YES on yes/no outcomes, and side 1 is NO. A multi-way question (e.g. price buckets) is several outcomes under one question, not extra sides. The side token appears in trades as:
  • Outcome side coin — #<encoding> (e.g. #90 = outcome 9, side 0 (YES))
  • Side token — +<encoding> (e.g. +91 = outcome 9, side 1 (NO))
You usually don’t construct these manually — the API/MCP exposes outcomeId and side separately and handles the encoding internally.

​
Settlement rules

  • Settlement — dir_id = 0 AND px ∈ {0, 1}
  • Pair redemption — dir_id = 0 AND px ≈ 0.5 (two-way market)
  • Auction-phase clearing — dir_id = 0 AND px ≈ 0.33333 (three-way bucket)
  • Quote token — HIP-4 outcomes settle in USDH, not USDC

​
Tool catalog

​
Why hip4_perp_position_context matters

This is the most interesting tool in the HIP-4 suite. It joins one outcome’s current net-positive holders to currently open perp positions on the same underlying asset, then labels each holder. Holders are wallets that traded the outcome in the last days (default 14, max 60) and still hold net contracts. signal is aligned, hedge or prediction_native:
  • aligned — the perp position is in the same direction as the outcome bet (e.g. holding the YES side of “BTC > $100k” AND long BTC perps → conviction trade)
  • hedge — the perp position is opposite the outcome bet (e.g. holding YES AND short BTC → hedge)
  • prediction_native — no underlying perp position (e.g. pure prediction market participant)
It returns per-side wallet counts, long/short wallet counts, net underlying notional, and the top wallets with their signal label. Use it when a user asks:
  • “Are outcome traders also exposed to the same asset?”
  • “Is this side directional or hedged?”
  • “Which large outcome holders have no perp exposure?”

​
Indexing assumptions

If you’re building on raw L1 data, the indexing convention is:
  • trades.coin LIKE '#<encoding>' for HIP-4 fills
  • Settlement detection by (dir_id, px) combinations described above
  • Cross-product overlap requires joining trades on outcome coins with live_positions on the underlying
The MCP tools handle all of this — you only need to understand it if you’re querying the database directly.