Skip to main content
Glama

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)

Related MCP server: Neleus MCP

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

  • Read endpoints (outcomeMeta, L2 book, mids, positions, candles, fills, orders)

  • Encoding helpers

  • PriceBinary description parsing

  • Search/filter outcomes

  • 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

Available Tools

10 tools
encoding_helperB

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

Inputs: side (required), outcomeId (required).

get_outcome_bookB

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

Inputs: side (required), outcomeId (required), network.

get_outcome_candlesA

Get OHLCV candle data for an outcome side. Useful for charting price history of prediction market positions.

Inputs: side (required), endTime (required), outcomeId (required), startTime (required), +2 more.

get_outcome_depth_summaryB

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

Inputs: network.

get_outcome_open_ordersB

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

Inputs: user (required), network.

get_outcome_positionsA

Get a user's outcome token balances (positions in prediction markets). Filters spot balances to outcome tokens only.

Inputs: user (required), network.

get_outcome_pricesA

Get mid prices for all outcome markets. Returns decoded outcome IDs, side names, and current mid prices.

Inputs: network.

get_outcome_tradesA

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

Inputs: user (required), network.

list_outcomesB

List all HIP-4 outcome markets with metadata, side specs, and linked questions. Returns outcome IDs, names, descriptions, and for priceBinary markets: underlying asset, target price, expiry, and period.

Inputs: network.

search_outcomesA

Search and filter outcome markets by underlying asset, type, or keyword. Useful for finding specific prediction markets (e.g. all BTC binary markets).

Inputs: type, keyword, network, activeOnly, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool targets a distinct data type (market info, prices, orderbook, user data, encoding), but get_outcome_prices and get_outcome_depth_summary both return price-related data for all markets, which could cause minor confusion. Descriptions are clear enough to differentiate them.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (list_, get_, search_), but 'encoding_helper' breaks the pattern by using a noun phrase. The rest are highly consistent, with all get_ tools prefixed uniformly.

    Tool Count5/5

    10 tools is well within the optimal 3-15 range and each covers a specific aspect of HIP-4 outcome markets (listing, pricing, orderbook, user positions, trades, etc.). No tool feels redundant or unnecessary.

    Completeness4/5

    The server effectively covers read-only market data needs: listing, searching, prices, depth, candles, and user account data. The only notable gap is the lack of order placement/cancellation, but the server appears intended for data retrieval, not trading. A single-market fetch could also be useful but list_outcomes already provides all metadata.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables interaction with the Hyperliquid DEX for retrieving market data, managing positions, and executing trades. Supports both testnet and mainnet operations with comprehensive trading tools including order placement, cancellation, and portfolio management.
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Hyperliquid markets for technical analysis, order book data retrieval, and cryptocurrency trading. Supports read-only market access without credentials and authenticated trading operations via private key configuration.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Query live HIP-4 prediction market data on Hyperliquid - real-time odds, orderbooks, trades, candles, user positions, and portfolio analysis via 10 MCP tools.
      10
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides read-only tools to query live Polymarket prediction-market data via the public Gamma API, enabling search, browsing, and detailed market and event information.
      4
      MIT