Metadata-Version: 2.4
Name: mcpxyz
Version: 0.2.1
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)

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.

## Install

```bash
# from PyPI (recommended)
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:

```bash
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:**

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