> For the complete documentation index, see [llms.txt](https://liquidiction.gitbook.io/liquidiction-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://liquidiction.gitbook.io/liquidiction-docs/developers/mcp-server.md).

# MCP Server

The Liquidiction MCP server gives MCP-compatible agents read-only access to live HIP-4 prediction-market data. It connects directly to Hyperliquid's public API; it does not hold keys or submit trades.

## Install

Requires Node.js 20 or newer and npm.

```bash
git clone https://github.com/Liquidiction/liquidiction-mcp.git
cd liquidiction-mcp
npm ci
```

Mainnet is the default. To use testnet, set `HL_API_URL=https://api.hyperliquid-testnet.xyz` in the environment used to launch the server.

## Connect a Client

### Claude Desktop

Add the server to `claude_desktop_config.json`, using the absolute path on your machine:

```json
{
  "mcpServers": {
    "liquidiction": {
      "command": "node",
      "args": ["/absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs", "/absolute/path/liquidiction-mcp/mcp-server.ts"],
      "env": {
        "HL_API_URL": "https://api.hyperliquid.xyz"
      }
    }
  }
}
```

Use absolute paths to both installed files. On Windows, forward-slash paths such as `C:/Users/you/liquidiction-mcp/mcp-server.ts` work. This launch command uses the installed runtime even when the client starts from another directory. Restart Claude Desktop after saving the configuration.

### Claude Code

```bash
claude mcp add liquidiction -- node /absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs /absolute/path/liquidiction-mcp/mcp-server.ts
```

### Other MCP Clients

Configure a stdio server with this command:

```bash
node /absolute/path/liquidiction-mcp/node_modules/tsx/dist/cli.mjs /absolute/path/liquidiction-mcp/mcp-server.ts
```

## Environment

| Variable     | Default                       | Description                                                          |
| ------------ | ----------------------------- | -------------------------------------------------------------------- |
| `HL_API_URL` | `https://api.hyperliquid.xyz` | Hyperliquid API origin; set the testnet origin only for testnet data |

## Tools

The distributable server exposes 10 tools:

| Tool                 | Input                                         | Result                                                    |
| -------------------- | --------------------------------------------- | --------------------------------------------------------- |
| `list_markets`       | None                                          | Active outcomes grouped with current prices               |
| `get_market_detail`  | `outcome_id`                                  | Metadata and side prices for one outcome                  |
| `get_market_summary` | None                                          | Enriched market overview and settlement metadata          |
| `get_orderbook`      | `outcome_id`, optional `side`                 | Top bids, asks, and spread                                |
| `get_prices`         | None                                          | Current mids for all `#N` outcome coins                   |
| `get_candles`        | `coin`, optional `interval`, optional `hours` | OHLCV history                                             |
| `get_recent_trades`  | `coin`                                        | Recent public trades                                      |
| `get_user_fills`     | `address`, optional `limit`                   | Public HIP-4 fills for a wallet                           |
| `get_open_orders`    | `address`                                     | Public resting HIP-4 orders                               |
| `get_user_positions` | `address`                                     | Balances, venues, selections, held shares and mark values |

`coin` inputs accept the current `#N` format. The server also normalizes explicit `+N`, legacy `@N` and bare numeric input to `#N` before calling Hyperliquid. Wallet `+N` balances expose both their raw coin and canonical `#N` identifier. Ordinary spot `@N` response rows are excluded from outcome holdings and fills.

## Wallet and cross-deployer inspection

`get_user_positions` takes a known wallet address. It returns JSON text containing `address`, `fetchedAt`, `source`, a snapshot note and a `positions` array. Each position includes the outcome ID, side, venue, deployer address, available market/selection labels, total shares, held shares, unheld shares, mark price and marked value. Raw coin and contract descriptions are preserved.

The server reads Hyperliquid directly. It does not search Liquidiction's wallet index to discover cross-deployer holders or automatically merge contracts. The same team can be side 0 on one venue and side 1 on another. Match participants using metadata and retain each contract's resolution rules.

Fractional shares are preserved. Missing marks or metadata remain `null`. Unheld shares are total minus held shares, not an execution guarantee. Balances, marks and metadata are separate reads, so the result is not an atomic snapshot. Scheduled times are contract metadata, not independently verified kickoff times.

## Update and verify

For an existing installation, run `git pull --ff-only`, then `npm ci`, and restart the MCP client.

```bash
npm run typecheck
npm test
```

These checks run offline. An optional read-only check calls all 10 tools against the selected network and compares the wallet positions with a separate Hyperliquid balance read:

```bash
npm run test:live -- 0xff16003f5bc3560daf4b9df62c191831af47387f 1866
```

The sample wallet and market can change or settle. Use a currently active outcome ID and a wallet with nonzero holdings. A wallet trading between the two reads can also cause the live comparison to fail.

## Example Prompts

* “List the most competitive HIP-4 markets.”
* “Show the order-book depth for outcome 1161, side 0.”
* “Fetch hourly candles for `#11610` over the last day.”
* “Show HIP-4 positions for `0x…`.”

The server is intentionally read-only. A trading agent needs its own secure signer and must use Hyperliquid's exchange API directly.

## Troubleshooting

* Empty testnet results usually mean the server was pointed at mainnet, or vice versa. Check `HL_API_URL`.
* A valid HIP-4 book, candle, or trade request should use `#N`. Direct `@N` mainnet requests can return `null`.
* Read operations require no API key, but normal Hyperliquid rate limits still apply.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://liquidiction.gitbook.io/liquidiction-docs/developers/mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.