hyperliquid-trading-agent

Hyperliquid Trading Agent — Claude plugin

Claude Code plugin for trading Hyperliquid perpetuals via natural language. Ships skills, strategies, and slash commands — and auto-spawns the MCP server (a separate repo) as a local stdio subprocess.

Two-repo architecture.

• MCP server (per-workspace settings, all the Hyperliquid logic): rsantamaria01/hyperliquid-trading-mcp, installed straight from git via uvx. Forked from edkdev/hyperliquid-mcp, risk layer adapted from sanketagarwal/hyperliquid-trading-agent.
• This plugin: just the Claude-facing layer. Skills, strategies, slash commands. Holds no secrets. Launches the server locally via uvx --from git+...; keys live in the workspace .env the server reads.

⚠️ Live exchange. Real money. Not audited. Default mode is dry-run.

What's in this plugin

.claude-plugin/plugin.json    # registers the uvx launch command + skills + commands
skills/
  setup/                       # /hta-setup — install uv + create the workspace .env
  settings/                    # /hta-settings — view/change per-workspace runtime config
  strategy/                    # /hta-strategy — pick or describe a strategy
  market-analysis/             # /hta-analyze — read setups
  trade-cycle/                 # one iteration: inline fetch + per-strategy eval (per tick)
  trade-loop/                  # the loop: repeat trade-cycle on a cadence + `close`
    leaf-contract.md           # (crypto × strategy) evaluation rubric / verdict fields
  portfolio-review/            # /hta-positions
  risk-audit/                  # /hta-risk-audit
commands/                      # slash-command entry points
strategies/                    # pluggable .md strategy definitions
LOG-SCHEMA.md                  # append-only log.jsonl event schema (local-only)

Install — 3 steps

1. Install uv + create the workspace .env

The plugin auto-spawns the server via uvx, so you just need uv on PATH and a .env in the folder you open Claude in:

# install uv (provides uvx), then restart the client
curl -LsSf https://astral.sh/uv/install.sh | sh

# in your workspace root, create .env with your wallet keys
cat > .env <<'EOF'
HYPERLIQUID_PRIVATE_KEY=0x...   # agent wallet key (signer only, no funds)
HYPERLIQUID_VAULT_ADDRESS=0x... # main wallet address (the funded one)
EOF
chmod 600 .env

# never commit secrets or per-workspace settings
printf '.env\n.hl-mcp/\nlog.jsonl\n' >> .gitignore

The agent wallet must be created on Hyperliquid first (app.hyperliquid.xyz → Settings → API Wallets). uvx clones and builds the server from git on first run (so git must be on PATH).

2. Install this plugin

Claude Code (CLI) — install from a release tag via the marketplace:

/plugin marketplace add rsantamaria01/[email protected]
/plugin install hyperliquid-trading-agent@hyperliquid-trading

The @v0.8.0 pins the install to that release tag — bump it to install a newer version. Browse tags on the Releases page.

On enable, the plugin spawns uvx --from git+https://github.com/rsantamaria01/[email protected] hyperliquid-trading-mcp automatically. The server writes a startup banner to stderr:

hyperliquid-trading-mcp [DRY-RUN] — workspace: /path/to/workspace

[LIVE] there means real orders for this workspace.

Client support: the Claude Code CLI is the supported client — it sets CLAUDE_PROJECT_DIR and has uvx on PATH for spawned servers. GUI clients (e.g. Cowork) may not put uvx/npx on the GUI app's PATH or set CLAUDE_PROJECT_DIR; that path is untested. If a GUI client can't launch the server, point it at an absolute path ($(which uvx)) or set PATH in the server's env block.

3. Sanity check + configure

In Claude:

/hta-setup                                # walks first-time setup; verifies server
/hta-settings                             # see per-workspace config
/hta-trading-mode                         # confirms mode + wallet

Use

/hta-strategy                             # list strategies
/hta-analyze BTC ETH --interval 1h
/hta-trade-cycle BTC ETH --strategy breakout-bb
/hta-positions
/hta-risk-audit
/hta-cancel BTC
/hta-settings set max_leverage=5
/hta-settings go-live                     # flips live_trading: true after confirm

Looping trade cycle (orchestrator + background job)