HYPERLIQUID-MCP-TRADING-SYSTEM

# HYPERLIQUID-MCP-TRADING-SYSTEM A **Rust** trading backend for **Hyperliquid**, exposed as both an **MCP server** (for AI agents) and a **REST adapter** (for apps). Built to power an autonomous AI trading runtime. [](LICENSE) ## What this is One backend, two faces, every Hyperliquid asset: - **MCP server (stdio)** — every trading capability is a typed MCP tool. Drop the binary into Claude Code / Claude Desktop / any MCP-aware agent and the model can read markets, manage positions, place orders, and move funds with a built-in risk gate. - **REST adapter (Axum)** — the same surface over HTTP for web/mobile/CLI apps. Money-movement endpoints (`/exchange/usd_send`, `/exchange/withdraw`, `/exchange/spot_send`) require an `Idempotency-Key`. Both faces share one execution path: `hl-info` (read) → `hl-risk` (gate) → `hl-exchange` (signed write). Signatures are byte-identical to the official Hyperliquid Rust SDK — golden vectors pin the L1 phantom-agent flow and the `HyperliquidTransaction:*` user-signed flow. ## Crates | crate | role | |---------------|------| | `hl-core` | wire-shape action enums; EIP-712 + msgpack signing; cloid; number formatting | | `hl-info` | typed `/info` HTTP client (meta, mids, l2Book, clearinghouse, fills, candles, funding) | | `hl-exchange` | signed `/exchange` HTTP client; asset registry; monotonic nonce | | `hl-stream` | WebSocket subscriptions with auto-reconnect (allMids, l2Book, trades, candle, userEvents, userFills, …) | | `hl-risk` | per-asset notional caps, rolling-window cap, allowlist, kill switch | | `hl-strategy` | `Strategy` trait + `TradingIntent` data model — the seam the AI runtime will plug into | | `hl-mcp` | [`rmcp`](https://crates.io/crates/rmcp) stdio MCP server | | `hl-http` | Axum REST adapter (bearer auth + `Idempotency-Key`) | | `hl-cli` | `hl` binary: `hl mcp serve`, `hl http serve`, `hl info …`, `hl stream …`, `hl order …` | ## Quick start ```bash # Build everything cargo build --release # Pull live mids straight off Hyperliquid mainnet ./target/release/hl info mids # Watch the BTC orderbook ./target/release/hl info book BTC # Stream every trade for ETH ./target/release/hl stream trades:ETH # Serve the MCP server over stdio (this is the form Claude Code expects) HL_PRIVATE_KEY=0x... ./target/release/hl mcp serve # Serve the REST adapter on :8787 with a bearer token HL_PRIVATE_KEY=0x... HL_BEARER_TOKEN=secret ./target/release/hl http serve --bind 0.0.0.0:8787 ``` ## Adding the MCP server to Claude Code ```json { "mcpServers": { "hyperliquid": { "command": "C:\\path\\to\\hl.exe", "args": ["mcp", "serve"], "env": { "HL_NETWORK": "mainnet", "HL_PRIVATE_KEY": "0xYOUR_KEY" } } } } ``` The agent then sees these tools: - **Read** — `list_assets`, `get_all_mids`, `get_orderbook`, `get_candles`, `get_account`, `get_spot_account`, `get_open_orders`, `get_fills` - **Trade** — `place_order`, `cancel_order`, `modify_order`, `set_leverage`, `place_twap` - **Funds** — `usd_send`, `withdraw`, `spot_send`, `approve_agent` - **Risk** — `kill_switch`, `risk_status` ## Security - The private key lives only in the process that runs `hl` — it never leaves your machine. The MCP server signs locally; only the signature + action go to Hyperliquid. - **Use a dedicated API wallet** (HL "agent wallet") via `approve_agent` instead of your funded keypair. Trading agents need only L1 signing capability — they cannot withdraw with an agent key. - The risk engine is on by default. Tune `RiskPolicy` (per-asset notional caps, rolling-window cap, allowlist) before sharing the key with an autonomous bot. - Flip the master kill switch via the `kill_switch` MCP tool / `POST /risk/kill_switch` to halt every new order without restarting. ## Verified - 15 tests pass (`cargo test --workspace`) - Signing golden vectors match the official Hyperliquid Rust SDK byte-for-byte (L1 mainnet + testnet, `UsdSend`, `Withdraw`) - Live mainnet `info mids` / `info book BTC` confirmed against `api.hyperliquid.xyz` ## Roadmap - **AI trading runtime** (next crate) — an LLM-driven `Strategy` implementation that consumes this MCP server, makes buy/sell decisions on a tick, and routes them through the same risk gate. - HIP-3 perp DEXs (custom universes), vault management UI, builder-fee revenue share, sub-account orchestration. ## License MIT.