liquidiction-mcp

Purpose

Liquidiction MCP Server provides MCP-compatible AI agents with read-only access to Hyperliquid HIP-4 prediction markets. The server connects directly to Hyperliquid's public API and requires no API key, wallet connection, or signing permissions.

Main Capabilities

The server provides 10 tools (the specific names are not listed individually in the material, except for get_user_positions). The queryable content includes: real-time odds, order books, candlesticks, trade records, and positions.

get_user_positions Returns JSON text containing address、fetchedAt、source, a snapshot description, and positions array. Each record contains:

• coin、rawCoin、outcomeId、side、venue as well as the deployer address.
• Market and option labels resolved when contract metadata is available.
• shares(raw total count string),heldShares and unheldShares。
• markPrice and markedValue; when there is no valid mark price, it is null.
• Available contract times, outcome sources, counted game fields, and the raw description.

Usage

Environment requirements: Node.js 20 or newer and npm.

This is a stdio MCP server, so npm start will wait for an MCP client connection instead of opening a website. Mainnet is used by default. Set HL_API_URL=https://api.hyperliquid-testnet.xyzonly when testnet data is needed.

Updating an existing installation: run git pull --ff-only、npm ci, then restart the MCP client.

After installing dependencies, configure the client using an absolute path. This uses the installed runtime and works even if the client working directory is elsewhere. On Windows, use a path 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 the configuration.

For Claude Code: the material provides the corresponding configuration method but does not give the complete configuration code. For clients started from the repository directory,npx tsx mcp-server.ts also works.

Result-type API requests use #N. Explicit coin inputs also accept +N, legacy @N , and pure numeric aliases, and normalize them to #N. Wallet balances returned as +N retain their original coin while exposing the normalized #N identifier. Ordinary spot @N rows are not classified as outcome positions or trades.

Example of a cross-deployer position query: ask the agent to "show this wallet's HIP-4 positions, including venue, team, total shares, and held shares. Compare positions on the same event, but do not merge their contracts."

Applicable Scenarios

• Let AI agents query real-time data from Hyperliquid HIP-4 prediction markets.
• View a wallet's prediction market positions and balances.
• Compare positions on the same event across different venues (outcome and trade.xyz).

Limitations

• Do not assume that side 0 represents the same team across different venues. outcome and trade.xyz may list the same event with the opposing participants in reverse order. The tools preserve distinct contracts and their rules, do not certify equivalence, and do not automatically merge positions.
• unheldShares is total shares minus held shares, and does not guarantee that an order can be executed.
• Reads are not atomic snapshots. Mark prices are estimates, not executable sell quotes.
• Missing active market metadata remains as null; This server does not provide historical metadata for every settled contract.
• A known wallet address must be provided. This server will not search the index to find wallets holding a specific market combination.

Development and Verification

The regression test suite runs offline and covers the current balance format, direction reversal across deployers, held shares, fractional balances, missing mark prices, input validation, and API errors.

An optional read-only smoke check starts a real MCP stdio client and calls all 10 tools against the configured Hyperliquid network. The example uses a real wallet, so positions may change. If it no longer has a position, choose another wallet and an active outcome ID. The check compares the MCP position with a separate balance read and may fail if the wallet trades between the two reads. Normal Hyperliquid rate limits apply.

License

MIT License. This server never submits transactions.