The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Liquidiction MCP listing page.
Read-only HIP-4 prediction-market tools for MCP-compatible agents. The server connects directly to Hyperliquid's public API. No API keys, wallet connection or signing permissions are required.
Requires Node.js 20 or newer and npm.
This is a stdio MCP server, so npm start waits for an MCP client rather than opening a website. Mainnet is the default. Set HL_API_URL=https://api.hyperliquid-testnet.xyz only when you want testnet data.
Existing installations: run git pull --ff-only, npm ci, then restart your MCP client.
After installing dependencies, configure your client with absolute paths:
This uses the installed runtime and works even when the client's working directory is elsewhere. On Windows, use paths such as C:/Users/you/liquidiction-mcp/mcp-server.ts and the corresponding node_modules/tsx/dist/cli.mjs path. Restart the client after changing its configuration.
For Claude Code:
For clients that launch from the repository directory, npx tsx mcp-server.ts also works.
| Tool | Input | Result |
|---|---|---|
list_markets | None | Active outcomes, selections, venues and prices |
get_market_detail | outcome_id | Metadata, venue, selections and side prices |
get_market_summary | None | Market overview and available settlement metadata |
get_orderbook | outcome_id, optional side | Top bids, asks and spread |
get_prices | None | Current outcome mid-prices |
get_candles | coin, optional interval, optional hours | OHLCV history |
get_recent_trades | coin | Recent public trades for the selected outcome side |
get_user_fills | address, optional limit | Recent public HIP-4 fills for a wallet |
get_open_orders | address | Public resting HIP-4 orders |
get_user_positions | address | Positions, venues, selections, held shares and mark values |
Outcome API requests use #N. Explicit coin inputs also accept +N, legacy @N and bare numeric aliases and normalize them to #N. Wallet balances returned as +N retain their raw coin and also expose the canonical #N identifier. Ordinary spot @N rows are not classified as outcome holdings or fills.
Ask your agent:
Show the HIP-4 positions for this wallet, including venue, team, total shares and held shares. Compare positions on the same fixture without merging their contracts.
get_user_positions returns JSON text with address, fetchedAt, source, a snapshot note and a positions array. Each row includes:
coin, rawCoin, outcomeId, side, venue and deployer address.shares, the original total string, heldShares and unheldShares.markPrice and markedValue, or null when a valid mark is unavailable.Do not assume side 0 means the same team across venues. Outcome and trade.xyz can list a fixture in opposite participant order. The tools preserve distinct contracts and their rules; they do not certify equivalence or automatically merge positions.
unheldShares is total minus held shares, not a guarantee that an order can execute. Reads are not an atomic snapshot. Marks are estimates, not executable sale quotes. Missing active-market metadata remains null; this server does not supply historical metadata for every settled contract.
Supply a known wallet address. This server does not search an index for wallets holding a particular combination of markets.
The regression suite runs offline and covers current balance formats, cross-deployer side reversal, held shares, fractional balances, missing marks, input validation and API errors.
An optional read-only smoke check launches a real MCP stdio client and calls all 10 tools against the configured Hyperliquid network:
The example is a live wallet, so holdings can change. If it no longer has positions, choose another wallet and active outcome ID. The check compares MCP holdings against a separate balance read and can fail if the wallet trades between reads. Normal Hyperliquid rate limits apply.
MIT licensed. This server never submits trades.