Tutorial · Claude Code

Trade Hyperliquid with Claude Code — step by step.

This tutorial walks through installing the Keel MCP in Claude Code, prompting Claude to compose a Hyperliquid carry strategy, running a real backtest against HL funding and price, and reviewing the share URL. Claude composes; the compiled artifact runs without Claude in the trade loop.

Install the Keel MCP Read the MCP product page
By Keel Research Team · Updated May 20, 2026
The tutorial

Six steps from install to a verified backtest.

Each step is a single prompt or a single command. Total time is well under fifteen minutes once the install completes.

01

Install Keel

Install the keel-trade package with pipx (recommended) or uv. The install brings the keel CLI, the DSL validator, the local stdio MCP server, and access to the 182-component typed strategy library — all from a single Python entry point. No project dependencies to manage; the install is isolated.
pipx install keel-trade

# Or via uv:
uv tool install keel-trade

# Verify
keel --version
keel --help
02

Register the MCP with Claude Code

Wire the local stdio MCP into Claude Code. This registers the keel mcp serve subprocess as a tool surface Claude can call — no hosted endpoint involved, no network round-trip for the MCP transport itself. Claude communicates with the local server over stdio; the server hits Keel's API as your authenticated user.
claude mcp add keel -- keel mcp serve

# Confirm registration
claude mcp list
03

Connect to Keel from inside Claude

Open Claude Code in any project and say “Connect to Keel.” Claude calls keel_auth_login, your browser opens to app.usekeel.io/oauth/connect for OAuth 2.1 + PKCE consent, and refreshable tokens land in ~/.keel/config.yaml. If you would rather pre-login from the terminal, keel auth login from the shell is equivalent — Claude picks up the same tokens.
04

Prompt Claude to compose a strategy

Drop the strategy thesis into Claude as a single prompt:

“Build me a funding-carry strategy on Hyperliquid using a carry signal and a funding-level regime. Universe: top 30 perps. Timeframe: 1d.”

Internally Claude calls keel_components_search to find the carry signal and the funding-level regime in the 182-component library, then calls keel_strategy_compose to author the typed DSL — validated at compose time, no Python script in sight. Claude returns a strategy ID and a structural summary you can review.

05

Run a backtest

Ask Claude to run the strategy against real Hyperliquid history:

“Backtest that strategy from 2024-08-15 to 2026-04-30 and summarize.”

Claude calls keel_backtest_run --wait, the deterministic engine runs against Hyperliquid 15-minute bars and 1-hour funding, and Claude returns metrics plus a share URL. Open the share URL to see the full tearsheet: verified Keel backtest — Sharpe 2.17, +79.6% return, -9.7% max DD, 48.7% win rate.

06

Iterate, then (optionally) deploy

Forking is the fast loop: “Fork that strategy and try a different regime threshold.” Claude calls keel_strategy_fork, patches the parameter, and reruns the backtest so you can compare.

Deployment is opt-in and gated by two locks. First, keel auth login --scope live requests the live-trading OAuth scope from the same browser consent flow. Second, keel arm live set --account <id> arms the local CLI against the specific Hyperliquid sub-account you want to trade. Defense in depth — Claude alone cannot wire a strategy to your funds. See /docs/sdk and /keel-mcp for the full deployment surface.

Common mistakes

Three failure modes to avoid.

Most of the friction people hit on this flow comes from one of these three patterns. Each has a one-line fix.

Skipping `keel_auth_login` first

The agent dives into keel_strategy_compose or keel_backtest_run without authenticating first. The remote tools return an auth-error envelope; Claude prints the error and asks what's wrong.

With Keel

Run keel_status first (or follow the suggested_next_action the error envelope hands back). When auth fails, the error tells the agent to call keel_auth_login. Follow that hint.

Asking Claude to 'just trade' for you

The agent has no execution loop. Claude is a build-time copilot; there is no continuous decision-making process in Claude that holds your account. Asking "just trade carry for me" produces a strategy artifact, not an autonomous trader.

With Keel

Claude composes the strategy; the compiled artifact runs deterministically against its schedule. The agent is not in the trade loop — by design.

Generating Python scripts that hit HL REST

A common failure pattern: Claude writes a one-off Python script that calls the Hyperliquid REST API directly. No engine behind it, no funding-aware backtest, no path from research to live, no live parity.

With Keel

Compose in the Keel DSL via the MCP. The same compiled artifact runs in backtest and live — bit-for-bit. The 182-component library has the primitives so you do not have to rewrite them.

FAQ

Common questions

What's the difference between Claude Code and Claude Desktop for Keel?

Claude Code, Cursor, Windsurf, and Codex are the tuned hosts — agent-mode detection auto-fires on each of those, and the install snippets in our docs target them directly. Claude Desktop supports MCP stdio servers but the surrounding integration (tool-call inspection, multi-step planning, agent-mode signals) is less mature. If you have a choice, start with Claude Code; everything else still works, just with rougher edges.

Does Claude need to be running while my strategy trades?

No. Once a strategy is deployed, the compiled artifact runs on Keel's execution surface against its own schedule. The agent is the build-time copilot, not the runtime. You can close Claude Code, restart your laptop, take a week off — the strategy keeps running until you pause or stop it.

Can I version my Keel strategy in git?

Yes. strategy.py is the source — a plain Python file with a create_strategy() factory that returns a typed DSL graph. Commit it like any other code. The CLI handles upload + remote validation: keel strategy create reads the file, validates against the live component registry, and uploads. Claude composing the strategy is one path; hand-editing the Python file and pushing through the CLI is another. Both produce the same artifact.

Does Claude have access to my private key?

No. Live execution on Hyperliquid uses native delegated signing — your wallet signs a delegation once via the web app, and Keel's executor places orders within that delegation's permissions. Keel never holds funds. To trade live, both the OAuth live scope and the local arming step must be set — two locks, both required, neither shippable by Claude alone.

What if `claude mcp add` fails?

Three common failure modes. (1) Claude Code <= 1.5 does not support MCP — upgrade to the latest version. (2) The keel binary is not on PATH; check that pipx install keel-trade completed cleanly and which keel resolves to the pipx shim. (3) A server named "keel" is already registered — run claude mcp remove keel, then re-add. If the registration succeeds but Claude reports the server as not responding, run keel mcp serve directly in a terminal to see the startup error.

Related

Keep exploring

Build a trading bot with Claude

The broader-intent sibling tutorial — what a "trading bot" actually is on Keel, and how Claude collaborates to build one.

Keel MCP — product page

Full product page for the Keel MCP server: install matrix, tool reference, prompts that work, demo recording.

Claude on Hyperliquid

The pillar page — Claude-driven strategy development on Hyperliquid, with the verified funding-carry share URL as the proof artifact.

What will you build?

Live on Hyperliquid in minutes.

Get started
Non-custodial
Your keys never leave your wallet. Your strategies run on your account — Keel never holds funds.
Same code, backtest to live
The strategy that passed your backtest is the strategy that trades. Same pipeline, no surprises.
Full visibility
See every position, trade, and decision in real time. Pause anytime. Your account, your control.