mcpxyz 0.1.0

MCP server for trade.xyz — analysis and trading of the xyz HIP-3 markets (xyz:AAPL, xyz:GOLD, ...) on Hyperliquid, with in-code guardrails. Fork of hyperliquid-mcp.

mcpxyz — MCP server for trade.xyz (HIP-3 on Hyperliquid)

An MCP server that lets an AI assistant (Claude Desktop, Claude Code, …) analyse and trade the xyz markets — tokenized equities, commodities and indices like xyz:AAPL, xyz:GOLD, xyz:NVDA, xyz:XYZ100 — exposed by trade.xyz.

trade.xyz has no proprietary API: it is a UI over the xyz HIP-3 perp dex deployed on Hyperliquid. Everything here goes through the standard Hyperliquid API, with markets namespaced xyz:.

⚠️ Not financial advice. Trading involves risk of loss. Use at your own risk.

Safety model

This server signs financial transactions, so guardrails are enforced in code (not via the prompt):

• Read-only by default — no order is signed unless READ_ONLY=false and a key is set.
• Delegated API wallet only — use a Hyperliquid API wallet (no withdrawal rights). The withdraw tool has been removed entirely.
• Asset whitelist — writes are limited to ALLOWED_ASSETS (empty ⇒ all writes blocked).
• Per-order caps — MAX_ORDER_SIZE, MAX_ORDER_NOTIONAL_USD, MAX_LEVERAGE.
• Two-step orders — place_order returns a preview + token; nothing is signed until you call confirm_order.
• Kill switch — cancel_all_orders is always available and never whitelisted.

See SECURITY.md for the full policy and key-handling guidance.

Tools

Market data (read-only): get_market_data, get_candle_data, get_l2_orderbook, get_funding_rates, calculate_min_order_size.

Account: get_positions (xyz isolated margin account), get_spot_user_state, get_user_fees, update_leverage, transfer (move collateral between core / spot / xyz).

Orders: place_order (preview) → confirm_order, cancel_order, cancel_all_orders, bulk_cancel_orders, modify_order, get_open_orders, get_order_status, get_user_fills, get_user_fills_by_time.

Assets are accepted namespaced (xyz:AAPL) or bare (AAPL, apple) — they are normalized automatically.

Install

# from PyPI (once published)
uvx mcpxyz

# or from source
uvx --from git+https://github.com/akugone/mcp-xyz mcpxyz

Get a delegated API wallet

1. In the Hyperliquid / trade.xyz UI, create an API wallet (a.k.a. agent wallet). It can trade but cannot withdraw funds.
2. Copy its private key. This is what you put in HYPERLIQUID_PRIVATE_KEY — never your main account key.

Claude Desktop config

Configuration lives in claude_desktop_config.json (there is no .env to fill as an end user). Generate a ready-to-paste snippet with:

mcpxyz init            # analysis only (read-only)
mcpxyz init --trading  # with a trading env block to fill in

Then merge the xyz entry into the mcpServers object and fully restart Claude Desktop. The two cases:

Analysis only — zero config, no key:

{
  "mcpServers": {
    "xyz": { "command": "uvx", "args": ["mcpxyz"] }
  }
}

Reads (prices, funding, candles, orderbook) work immediately. No key ⇒ fully read-only, no order can be placed.

Trading — add your own delegated API wallet key:

{
  "mcpServers": {
    "xyz": {
      "command": "uvx",
      "args": ["mcpxyz"],
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "0x<your_delegated_api_wallet_key>",
        "HYPERLIQUID_USER_ADDRESS": "0x<your_main_account_address>",
        "READ_ONLY": "false",
        "ALLOWED_ASSETS": "xyz:AAPL,xyz:GOLD",
        "MAX_ORDER_NOTIONAL_USD": "100"
      }
    }
  }
}

Your key stays on your machine — it is only read from this env block (or, for local development, a gitignored .env) and never sent anywhere.

Environment variables

Variable	Default	Description
HYPERLIQUID_PRIVATE_KEY	—	Delegated API wallet key. Empty ⇒ read-only.
HYPERLIQUID_USER_ADDRESS	wallet addr	Address to query positions/fills for.
HYPERLIQUID_TESTNET	false	Use testnet instead of mainnet.
READ_ONLY	true	Must be false (and a key set) to sign anything.
XYZ_DEX	xyz	HIP-3 perp dex namespace.
ALLOWED_ASSETS	—	Comma-separated whitelist for writes (e.g. xyz:AAPL,xyz:GOLD). xyz:* allows all xyz markets. Empty ⇒ writes blocked. Reads are never restricted.
MAX_ORDER_SIZE	—	Max size per order.
MAX_ORDER_NOTIONAL_USD	—	Max notional (USD) per order.
MAX_LEVERAGE	—	Max leverage for update_leverage.
HYPERLIQUID_MCP_SHOW_LOGS	false	Keep false in production.

Usage flow

1. Explore read-only: get_market_data xyz:AAPL → candles → L2 → funding.
2. Check get_positions.
3. place_order (limit, away from the price) → review the preview → confirm_order.
4. cancel_order / cancel_all_orders.

Validation & tests

• uv run pytest — offline unit tests (guardrails, models, tool registration, order flow).
• Write-path validation on testnet: see docs/VALIDATION.md and scripts/validate_testnet.py.

Transports

mcpxyz                       # stdio (default)
mcpxyz --transport http --port 3000
mcpxyz --transport sse  --port 3000

Credits & license

Fork of midodimori/hyperliquid-mcp (MIT). Adapted for the trade.xyz HIP-3 markets with in-code guardrails. Licensed under MIT.