Metadata-Version: 2.4
Name: mcpxyz
Version: 0.3.0
Summary: 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.
Project-URL: Homepage, https://github.com/akugone/mcp-xyz
Project-URL: Repository, https://github.com/akugone/mcp-xyz
Project-URL: Issues, https://github.com/akugone/mcp-xyz/issues
Project-URL: Documentation, https://github.com/akugone/mcp-xyz#readme
Author: akugone
License: MIT License
        
        Copyright (c) 2025 Hyperliquid MCP Server
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: defi,hip-3,hyperliquid,mcp,trade.xyz,trading,xyz
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: asyncio-throttle>=1.0.2
Requires-Dist: eth-account>=0.13.7
Requires-Dist: fastmcp>=3.0
Requires-Dist: hyperliquid-python-sdk>=0.24.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == 'dev'
Requires-Dist: isort>=6.0.1; extra == 'dev'
Requires-Dist: mcp[cli]>=1.12.2; extra == 'dev'
Requires-Dist: mypy>=1.17.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.1; extra == 'dev'
Requires-Dist: pytest>=8.4.1; extra == 'dev'
Requires-Dist: python-dotenv>=1.1.1; extra == 'dev'
Requires-Dist: ruff>=0.12.5; extra == 'dev'
Description-Content-Type: text/markdown

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

[![PyPI](https://img.shields.io/pypi/v/mcpxyz.svg)](https://pypi.org/project/mcpxyz/)
[![Python](https://img.shields.io/pypi/pyversions/mcpxyz.svg)](https://pypi.org/project/mcpxyz/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-black.svg)](https://modelcontextprotocol.io)

An [MCP](https://modelcontextprotocol.io) 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](https://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](SECURITY.md) for the full policy and key-handling guidance.

## Tools

**Market data** (read-only): `get_markets_overview` (all markets in one call —
price, 24h change, funding, OI, volume; sortable for top movers), `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.

## Requirements

Python 3.11+ and one launcher: [`uv`](https://docs.astral.sh/uv/) (recommended),
`pip`, or `pipx`.

## Works with any MCP client

mcp-xyz speaks standard MCP (stdio / HTTP / SSE), so it works with **any
MCP-compatible client — regardless of the underlying LLM**: Claude Desktop, Claude
Code, Cursor, Cline, Continue, Windsurf, Zed, or your own agent via the Python /
TypeScript MCP SDKs. The examples below use Claude Desktop's config format; other
clients use the same `command` + `args` (+ `env`) in their own config file.

## Get a delegated API wallet (trading only)

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 your `HYPERLIQUID_PRIVATE_KEY`. **Never use your
   main account key.**

## Install — three ways

### 1. Clone the repo (best for builders)

Get the code, keep your config in a gitignored `.env`, and let your IDE agent wire
it in.

```bash
git clone https://github.com/akugone/mcp-xyz
cd mcp-xyz
cp .env.example .env    # analysis: leave as-is · trading: add your API wallet key
```

Then either **ask your IDE agent** (Claude Code, Cursor, …) to *"add this repo as
an MCP server"* — it reads this README and wires it up — or add it manually:

```json
{ "mcpServers": { "xyz": {
  "command": "uv",
  "args": ["--directory", "/absolute/path/to/mcp-xyz", "run", "mcpxyz"]
} } }
```

The `.env` in the folder is loaded automatically, so all config lives there (no
env block needed). For Claude Code, one command does it:

```bash
claude mcp add xyz -- uv --directory /absolute/path/to/mcp-xyz run mcpxyz
```

### 2. From PyPI (recommended for users)

No clone. Generate a ready-to-paste config with `init`:

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

Paste the snippet into your client's config, fill your key if trading, restart the
client. **No `uv`?** `pip install mcpxyz` (then use `mcpxyz` as the command) or
`pipx run mcpxyz` — same result.

### 3. Claude Desktop (copy-paste)

Config file: `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) · `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Merge the `xyz`
entry and fully restart Claude Desktop.

**Analysis only — zero config, no key:**

```json
{
  "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:**

```json
{
  "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:*",
        "MAX_ORDER_NOTIONAL_USD": "100"
      }
    }
  }
}
```

`ALLOWED_ASSETS: "xyz:*"` allows trading every xyz market. To restrict trading to
specific markets, list them instead, e.g. `"xyz:AAPL,xyz:GOLD"`.

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](docs/VALIDATION.md) and
  `scripts/validate_testnet.py`.

## Transports

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

## Credits & license

Fork of [midodimori/hyperliquid-mcp](https://github.com/midodimori/hyperliquid-mcp)
(MIT). Adapted for the trade.xyz HIP-3 markets with in-code guardrails. Licensed under
[MIT](LICENSE).
