Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt

Use this file to discover all available pages before exploring further.

HyperLiquid’s prediction markets (HIP-4) let you trade on real-world outcomes. This guide covers the full flow from discovery to settlement.
HIP-4 is currently active on testnet with sample outcomes. Mainnet has 0 outcomes live as of April 2026. This guide works for both networks. The trading flow is identical.

​
How predictions work

Each prediction market has multiple outcomes. Each outcome has two sides: YES and NO. These are traded as spot tokens on HyperLiquid’s spot rails, not as perpetuals.
  • YES tokens are worth 1iftheoutcomehappens,1 if the outcome happens, 0 if not
  • NO tokens are worth 1iftheoutcomedoesn′thappen,1 if the outcome doesn't happen, 0 if it does
  • Prices reflect the market’s probability estimate
  • Settlement is automatic via L1 mark price

​
Step 1: Discover available markets

curl -H "x-api-key: YOUR_KEY" "https://hyper.polynode.dev/v2/prediction/markets"
Each market returns its outcomes with their encoding numbers.

​
Step 2: Understand the asset ID system

Every prediction outcome token has a unique encoding: 
encoding = 10 * outcome_id + side_index
Where side_index is 0 for YES, 1 for NO. The coin name uses the # prefix: #39890 means outcome 3989, YES side. The numeric asset ID is 100,000,000 + encoding. So #39890 has asset ID 100,039,890.

​
Examples

Outcome IDSideEncodingCoin nameAsset ID
3989YES39890#39890100,039,890
3989NO39891#39891100,039,891
3990YES39900#39900100,039,900

​
Step 3: Get collateral

Prediction markets trade in USDH, not USDC. To get USDH:
  1. Transfer USDC to your HyperLiquid spot balance
  2. Buy USDH at the spot pair @180 (USDH/USDC)

​
Step 4: Check the order book

# L2 order book for a prediction outcome
curl -H "x-api-key: YOUR_KEY" \
  "https://hyper.polynode.dev/exchange/prediction/orderbook?outcome=3989&side=0"
Or use the standard orderbook endpoint with the coin name: 
curl -H "x-api-key: YOUR_KEY" \
  "https://hyper.polynode.dev/v2/orderbook?coin=%2339890"
Note: %23 is the URL-encoded # character.

​
Step 5: Place an order

Use the exchange API to place orders on prediction tokens. The order format is the same as any HyperLiquid spot order. 
# Via the exchange API (requires registered wallet)
curl -X POST "https://hyper.polynode.dev/exchange/order" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "coin": "#39890",
    "is_buy": true,
    "sz": "10",
    "limit_px": "0.65",
    "order_type": {"limit": {"tif": "Gtc"}}
  }'
This places a limit buy for 10 YES tokens at $0.65 each.

​
Step 6: Track in the stream

Subscribe to prediction market events in the WebSocket stream: 
{"action": "subscribe", "filters": {"assets": ["#39890"]}}
You’ll see orders, fills, and cancellations for this outcome token, tagged with consensus: "confirmed". 
ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  if (event.type === "fill" && event.asset === "#39890") {
    console.log(`Prediction fill: ${event.data.dir} ${event.data.sz} @ ${event.data.px}`);
  }
});

​
Step 7: Settlement

When the outcome is determined:
  1. The YES token settles at 1,theNOtokenat1, the NO token at 0 (or vice versa)
  2. Settlement is automatic via the L1 mark price
  3. Your position is closed at the settlement price
  4. PnL is credited to your spot balance in USDH

​
Convenience endpoints

hypernode provides enriched prediction market endpoints:
EndpointWhat it returns
/v2/prediction/marketsAll prediction markets with outcomes
/v2/prediction/market?id=NSingle market details
/exchange/prediction/pricesCurrent prices for all outcome tokens
/exchange/prediction/orderbook?outcome=N&side=SL2 book for one outcome side
/exchange/prediction/trades?outcome=N&side=SRecent trades
/exchange/prediction/settled?outcome=NSettlement result

​
Testnet

To experiment with prediction trading on testnet:
  1. Get testnet USDC from the HyperLiquid testnet faucet
  2. Connect to the testnet stream: wss://hyper.polynode.dev/ws-testnet?key=YOUR_KEY
  3. Use the exchange API with network=testnet parameter
Testnet currently has sample outcomes for testing the full trading flow.