# polskidegen-hl-tracker

[![npm](https://img.shields.io/npm/v/polskidegen-hl-tracker)](https://www.npmjs.com/package/polskidegen-hl-tracker)
[![license](https://img.shields.io/npm/l/polskidegen-hl-tracker)](LICENSE)

**Model Context Protocol (MCP) server for Hyperliquid** — read-only, on-chain wallet analytics for any public address. Plug it into Claude Desktop (or any MCP client) and ask natural-language questions about positions, fills, funding, and realized PnL on Hyperliquid perps & spot.

No keys. No login. Public wallet address in → structured analytics out.

## Features

| Tool | What it returns |
|------|-----------------|
| `get_positions` | Open perp positions: size, entry, mark, unrealized PnL, ROE, leverage, liquidation price + account value / margin / withdrawable |
| `get_spot_balances` | Hyperliquid spot balances: free, locked, total (USD value when available) |
| `get_fills` | Last N days of fills (trades): timestamp, coin, side, size, price, direction (open/close), PnL, fee — up to 500 rows |
| `get_pnl_summary` | Realized PnL over `7d` / `30d` / `all`: total PnL, closed trades, win rate, avg ROI, best/worst trade, avg hold time, fees |
| `get_funding` | Funding payments over N days: net, paid, received, per-coin breakdown |
| `compare_wallets` | Side-by-side comparison of 2–5 wallets on 30d window (account value, PnL, win rate, avg ROI, top position) |
| `get_price` | Current market data for any HL perp: mid, mark, oracle, 24h change, funding rate, open interest, 24h volume |
| `get_top_traders` | Top N traders on Hyperliquid by PnL / ROI / volume over 24h / 7d / 30d / all-time. Covers all 30k+ accounts — no API key, uses HL's own public leaderboard source. Returns addresses you can pipe back into the other tools for deep-dive. |

## Installation

### Claude Desktop

Edit your `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add to `mcpServers`:

```json
{
  "mcpServers": {
    "polskidegen-hl-tracker": {
      "command": "npx",
      "args": ["-y", "polskidegen-hl-tracker@0.2.0"]
    }
  }
}
```

Restart Claude Desktop. The 7 tools appear in the tool picker.

### Other MCP clients

Any stdio-capable MCP client works. Run the binary directly:

```bash
npx -y polskidegen-hl-tracker@0.2.0
```

## Example prompts

Try these in Claude Desktop once installed:

- **Positions:** *"Show the open Hyperliquid positions for `0xea0027b6ea9b6d7d401b5266979cc3b3ca87a918`."*
- **Spot:** *"What spot tokens does `0x...` hold on Hyperliquid?"*
- **Fills:** *"List the last 7 days of Hyperliquid trades for wallet `0x...`."*
- **PnL:** *"Summarize 30-day realized PnL, win rate, and avg ROI for `0x...` on Hyperliquid."*
- **Funding:** *"How much did wallet `0x...` pay or receive in Hyperliquid funding over the last week?"*
- **Compare:** *"Compare Hyperliquid performance for these 3 wallets: `0x...`, `0x...`, `0x...`."*
- **Price:** *"What's the current Hyperliquid mark price and funding for HYPE?"*
- **Leaderboard:** *"Who are the top 5 most profitable Hyperliquid traders in the last 24 hours?"*
- **Leaderboard + deep-dive:** *"Pull the top 10 HL traders by 30d PnL, then show the current positions of the top 3."*

## Security

**This MCP is 100% read-only.** It does not require any private keys, seeds, mnemonics, or logins. Only a public wallet address (`0x` + 40 hex chars) is needed as input.

- All data comes from Hyperliquid's **public info endpoint** (`https://api.hyperliquid.xyz/info`).
- No external services, no telemetry, no analytics, no tracking.
- The `exchange` endpoint (which would require signing) is **never** called.
- No network calls are made to any host other than `api.hyperliquid.xyz`.

## Notes & limits

- `userFillsByTime` / `userFunding` return up to ~500–2000 events per request. `get_pnl_summary` covers up to 365 days but the underlying fills endpoint caps the result set — for extremely active traders, numbers over long windows reflect the capped sample.
- `avg hold time` in `get_pnl_summary` is approximate — it pairs closes with nearest prior opens on the same coin; if the matching open falls outside the fetched window, it's skipped.
- USD values for spot balances depend on whether the token has an active mark on `allMids`.

## Maintainer

Built by [**@polskidegen**](https://x.com/polskidegen) — Polish crypto/AI trader, building tools for the degen stack.

Issues / PRs: https://github.com/polskidegen/polskidegen-hl-tracker

## License

MIT — see [LICENSE](LICENSE).