HIP-4 documentation

Testnet · Exploratory documentation — not official Hyperliquid documentation.

Info endpoint — HIP-4 (testnet)

Same layout pattern as the official Hyperliquid GitBook: method badge, headers table, body fields, response tabs.

Content is Liquid Terminal research on prediction markets and # coins — not an official Hyperliquid page.

On this page

Intro & base URL REST — POST /info Retrieve outcome metadata (testnet-only)Retrieve candle snapshot (# coins)User fee schedule (userFees)User fills by time window (userFillsByTime)Outcome types Coin ID mapping WebSocket Channel: activeSpotAssetCtx Channel: l2Book

Official reference

Layout model: Info endpoint → Spot on GitBook.
Our fields documented here: outcomeMeta, candleSnapshot, plus WS subscribe/push examples.
Base URL for this chapter: https://api.hyperliquid-testnet.xyz/info

REST — POST /info

Each card below is one type in the JSON body (GitBook-style: headers, body table, collapsible example, response tabs). Use the right-hand On this page menu (desktop) or the inline chips above to jump.

Retrieve outcome metadata (testnet-only)

POSThttps://api.hyperliquid-testnet.xyz/info

Lists prediction outcomes, side specs, and grouped questions. Not available on mainnet API in our tests — use testnet.

Headers

Name	Value
Content-Type*	application/json

Body

Name	Type	Description
type*	String	Must be "outcomeMeta".

Example request

{
  "type": "outcomeMeta"
}

Response

{
  "outcomes": [
    {
      "outcome": 9,
      "name": "Who will win the HL 100 meter dash?",
      "description": "This race is yet to be scheduled.",
      "sideSpecs": [
        {
          "name": "Hypurr"
        },
        {
          "name": "Usain Bolt"
        }
      ]
    },
    {
      "outcome": 2243,
      "name": "Recurring",
      "description": "class:priceBinary|underlying:BTC|expiry:20260327-0300|targetPrice:71169|period:1d",
      "sideSpecs": [
        {
          "name": "Yes"
        },
        {
          "name": "No"
        }
      ]
    }
  ],
  "questions": [
    {
      "question": 1,
      "name": "What will Hypurr eat the most of in Feb 2026?",
      "description": "Hypurr has committed to weighing and recording daily food intake in a food journal.",
      "fallbackOutcome": 13,
      "namedOutcomes": [
        10,
        11,
        12
      ],
      "settledNamedOutcomes": []
    }
  ]
}

Retrieve candle snapshot (# coins)

POSThttps://api.hyperliquid-testnet.xyz/info

OHLCV history for a spot-style coin string. For HIP-4 pairs use the full #YES id (trailing zero), not the raw outcome id.

Headers

Name	Value
Content-Type*	application/json

Body

Name	Type	Description
type*	String	"candleSnapshot".
req*	Object	Request object — see nested fields.
req.coin*	String	e.g. "#22430" (YES leg of outcome 2243).
req.interval*	String	e.g. "1d", "1h".
req.startTime*	number	Unix ms.
req.endTime*	number	Unix ms.

Example request

{
  "type": "candleSnapshot",
  "req": {
    "coin": "#22430",
    "endTime": 1774569600000,
    "interval": "1d",
    "startTime": 1746057600000
  }
}

Response

[
  {
    "T": 1746057600000,
    "c": "0.512",
    "h": "0.52",
    "i": "1d",
    "l": "0.498",
    "n": 120,
    "o": "0.505",
    "t": 1774569600000,
    "v": "1936.0"
  }
]

User fee schedule (userFees)

POSThttps://api.hyperliquid-testnet.xyz/info

Per-user spot/perp fee rates and the default feeSchedule. Use a sentinel address for base schedule only. Used in HIP-4 fee research to compare outcome fills to userSpotCrossRate.

Headers

Name	Value
Content-Type*	application/json

Body

Name	Type	Description
type*	String	"userFees".
user*	String (0x…)	Wallet address; e.g. 0xff…f for default schedule only.

Example request

{
  "type": "userFees",
  "user": "0xffffffffffffffffffffffffffffffffffffffff"
}

Response

{
  "feeSchedule": {
    "cross": "0.00045",
    "add": "0.00015",
    "spotCross": "0.0007",
    "spotAdd": "0.0004"
  },
  "userCrossRate": "0.0",
  "userAddRate": "0.0",
  "userSpotCrossRate": "0.0",
  "userSpotAddRate": "0.0",
  "activeReferralDiscount": "0.0"
}

User fills by time window (userFillsByTime)

POSThttps://api.hyperliquid-testnet.xyz/info

Historical fills for a user between startTime and endTime (Unix ms). Outcome markets use @-prefixed coin names; fee is often in feeToken (base asset), not USDC — normalize for effective bps.

Headers

Name	Value
Content-Type*	application/json

Body

Name	Type	Description
type*	String	"userFillsByTime".
user*	String (0x…)	Wallet address.
startTime*	number	Unix ms (inclusive).
endTime*	number	Unix ms (inclusive).

Example request

{
  "type": "userFillsByTime",
  "user": "0xae551d73161bac3315c5ade0e2d499a44ebe2236",
  "startTime": 1769956276000,
  "endTime": 1769956277000
}

Response

[
  {
    "coin": "@10",
    "px": "0.59475",
    "sz": "1000.0",
    "dir": "Buy",
    "crossed": true,
    "fee": "0.56",
    "feeToken": "CHUTORO"
  }
]

Outcome types

How outcomeMeta rows map to market shapes we observed on testnet.

Type	Example	Description
Custom	outcome 9	Open question, N named outcomes
priceBinary	outcome 2243	Above/below threshold at expiry — YES/NO only
Recurring	outcome 2300	Auto-recreated priceBinary (15m, 1h, 1d, …)

Multi-outcome questions group several outcomes; each outcome still trades as its own YES/NO pair on the CLOB.

Coin ID mapping

Outcome tokens use #-prefixed names on the book.

Outcome 2243 → YES #22430, NO #22431
Formula: YES = "#" + (outcomeId × 10), NO = "#" + (outcomeId × 10 + 1)

Always pass the full # coin string to candleSnapshot — not the bare outcome id.

WebSocket

Example subscribe frames and push payloads from our HIP-4 research. markPx on YES legs reads like implied probability.

Channel: activeSpotAssetCtx

WebSocketwss://api.hyperliquid-testnet.xyz/ws

Subscribe per coin for mark/mid, volume, supply. markPx reads as implied probability on YES legs.

Subscribe (example)

Shape follows Hyperliquid WS patterns; verify against the latest official WS docs if your client fails to bind.

{
  "method": "subscribe",
  "subscription": {
    "type": "activeSpotAssetCtx",
    "coin": "#22430"
  }
}

Response

{
  "channel": "activeSpotAssetCtx",
  "data": {
    "coin": "#22430",
    "ctx": {
      "prevDayPx": "0.5",
      "dayNtlVlm": "976.651",
      "markPx": "0.515",
      "midPx": "0.515",
      "circulatingSupply": "1936.0",
      "dayBaseVlm": "1936.0",
      "totalSupply": "184467440737095.53125"
    }
  }
}

Channel: l2Book

WebSocketwss://api.hyperliquid-testnet.xyz/ws

levels[0] = bids (desc), levels[1] = asks (asc). Each # coin has its own book; pair minting mirrors across YES/NO.

Subscribe (example)

Shape follows Hyperliquid WS patterns; verify against the latest official WS docs if your client fails to bind.

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "#22430"
  }
}

Response

{
  "channel": "l2Book",
  "data": {
    "coin": "#22430",
    "levels": [
      [
        {
          "px": "0.5",
          "sz": "2000.0",
          "n": 2
        },
        {
          "px": "0.4",
          "sz": "50.0",
          "n": 1
        }
      ],
      [
        {
          "px": "0.53",
          "sz": "2048.0",
          "n": 1
        },
        {
          "px": "0.53055",
          "sz": "136.0",
          "n": 1
        },
        {
          "px": "0.56111",
          "sz": "887.0",
          "n": 1
        }
      ]
    ],
    "time": 1774545317611
  }
}