hip4-mcp

hip4-mcp

⚠️ EXPERIMENTAL — HIP-4 is currently live on Hyperliquid testnet only. Mainnet launch is expected in 2026 (no exact date announced). This server will be updated for mainnet once HIP-4 goes live.

MCP server for Hyperliquid HIP-4 prediction markets (outcome trading). Provides read-only tools for discovering, analyzing, and monitoring outcome contracts.

What is HIP-4?

HIP-4 adds outcome trading to Hyperliquid — fully collateralized binary contracts that settle to 0 or 1 based on whether an event occurs. Think prediction markets built natively on HyperCore's orderbook.

• Binary YES/NO contracts priced 0–1 (price = implied probability)
• No leverage, no liquidations — fully collateralized
• Settles in USDH (Hyperliquid's native stablecoin)
• Traded on HyperCore's central limit orderbook (same infra as perps/spot)

Install

npm install -g hip4-mcp

Or clone and build:

git clone https://github.com/yashhsm/hip4-mcp.git
cd hip4-mcp
npm install
npm run build

Configure in Claude Code

Add to your MCP config (.mcp.json or Claude Code settings):

{
  "mcpServers": {
    "hip4": {
      "command": "node",
      "args": ["/path/to/hip4-mcp/dist/index.js"]
    }
  }
}

Tools

list_outcomes

List all HIP-4 outcome markets with metadata, side specs, and linked questions. For priceBinary markets, returns parsed underlying asset, target price, expiry, and period.

get_outcome_book

Get the L2 orderbook for a specific outcome side. Returns bids, asks, spread, and depth summary.

get_outcome_prices

Get mid prices for all outcome markets with decoded outcome IDs and side names.

get_outcome_positions

Get a user's outcome token balances (prediction market positions).

get_outcome_depth_summary

Get depth summary across ALL outcome markets — bid/ask depth, spread, best prices for every active side.

search_outcomes

Search and filter outcomes by underlying asset (BTC, HYPE), type (priceBinary), or keyword. Optionally filter to only markets with orderbook depth.

get_outcome_candles

Get OHLCV candle data for an outcome side. Useful for charting price history.

get_outcome_trades

Get a user's fill history filtered to outcome markets only.

get_outcome_open_orders

Get a user's open orders filtered to outcome markets only.

encoding_helper

Convert between outcome IDs, side indices, coin symbols (#xxx), token names (+xxx), and asset IDs. Useful for understanding the HIP-4 encoding system.

HIP-4 Asset Encoding

Outcome assets use a special encoding on Hyperliquid:

| Component | Formula | Example (BTC outcome 2146, YES) | |-----------|---------|-------------------------------| | Encoding | 10 * outcomeId + side | 21460 | | Spot coin | #<encoding> | #21460 | | Token name | +<encoding> | +21460 | | Asset ID | 100_000_000 + encoding | 100021460 |

Side is 0 for the first outcome (usually YES), 1 for the second (usually NO).

Network

All tools accept a network parameter ("testnet" or "mainnet"), defaulting to "testnet".

• Testnet: https://api.hyperliquid-testnet.xyz
• Mainnet: https://api.hyperliquid.xyz

Testing

npm run build
node dist/test.js

Runs integration tests against the Hyperliquid testnet API.

Status

• [x] Read endpoints (outcomeMeta, L2 book, mids, positions, candles, fills, orders)
• [x] Encoding helpers
• [x] PriceBinary description parsing
• [x] Search/filter outcomes
• [x] Complementary pricing validation (YES + NO = 1)
• [ ] Write endpoints (place order, cancel) — coming with mainnet launch
• [ ] WebSocket subscriptions for real-time price updates
• [ ] USDH collateral management helpers

License

MIT