> 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.

## Hosted endpoint

The same tools are served over the MCP Streamable HTTP transport at:

```
https://liquidiction.xyz/api/mcp
```

No install, no auth, read-only. A discovery document lives at `https://liquidiction.xyz/.well-known/mcp.json`. Requests are rate limited per IP and across all callers, and answers are shared across callers for a few seconds (market metadata for 30 seconds, wallet fills for 30, open orders, prices and recent trades for 15). The endpoint is stateless: each POST carries exactly one JSON-RPC message (batch arrays are rejected with error -32600), so clients that need resumable server-to-client streams should use the local install below. Hosted `coin` inputs must be HIP-4 outcome coins and `address` inputs must be 0x addresses.

Claude Code:

```bash
claude mcp add --transport http liquidiction https://liquidiction.xyz/api/mcp
```

Claude Desktop or any client that takes a URL: enter the endpoint above as an HTTP MCP server.

## 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.

## Hosted sports-history MCP

The website also exposes a separate public, read-only MCP Streamable HTTP endpoint:

`https://liquidiction.xyz/api/mcp/sports`

Connect an HTTP-capable MCP client to that URL. The stateless endpoint supports standard initialization, `tools/list` and `tools/call`; POST requests accept `application/json, text/event-stream`. It does not open a persistent SSE stream or require an API key. Native clients may omit Origin; supplied browser Origins must be explicitly trusted Liquidiction origins.

| Tool                   | Input                                             | Result                                                                  |
| ---------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
| `find_sports_entities` | `query`, optional `kind`, optional `limit` (1–50) | Eligible teams/players, canonical profile URLs and archive coverage     |
| `get_sports_entity`    | `kind`, `sport`, `slug`, optional `page`          | Up to 20 market events, deployer listings and verified archived results |

Use identity fields returned by discovery, rather than guessing profile URLs. A team or player qualifies only after an actual HIP-4 listing is indexed; historical profiles persist. Archived sporting finals and market settlement are separate records. Missing verified results remain unavailable, and responses include source times and coverage. This is not a complete sports-results database.

The public [sports data guide](https://liquidiction.xyz/developers/sports-data) documents equivalent cached JSON endpoints and browser WebMCP tools. Browser tools use `document.modelContext` only when supported; this does not add capabilities to the separate local MCP project above.