# hip4-mcp

> **⚠️ EXPERIMENTAL** — HIP-4 is currently live on [Hyperliquid testnet](https://app.hyperliquid-testnet.xyz) 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](https://x.com/HyperliquidX/status/2018327360723202167) 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

```bash
npm install -g hip4-mcp
```

Or clone and build:

```bash
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):

```json
{
  "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

```bash
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