Keel — Hyperliquid trading agent
Build, backtest, and automate Hyperliquid trading strategies — typed, deterministic, live parity.
Open source Open in the app JSON README (API)
About
Build, backtest, and automate Hyperliquid trading strategies — typed, deterministic, live parity.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- keel-trade
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.5.6
- Stars
- 1
- Last push
- 2026-08-21T19:35:05Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:20
- Updated
- 2026-08-29 04:00:20
- Origin id
io.github.keel-trade/keel-trade
README
<p align="center">
<a href="https://usekeel.io/keel-mcp">
<img src="https://usekeel.io/og/keel-mcp.png" alt="keel-trade — Build, backtest, and automate Hyperliquid trading strategies with your agent" width="100%">
</a>
</p>
<h1 align="center">keel-trade</h1>
<p align="center">
<strong>The Keel CLI and stdio MCP server.</strong><br>
Build, backtest, and automate <a href="https://hyperliquid.xyz">Hyperliquid</a> trading strategies — with your agent in the loop for <em>creation</em> and a deterministic engine in the loop for <em>execution</em>.
</p>
<p align="center">
<a href="https://pypi.org/project/keel-trade/"><img src="https://img.shields.io/pypi/v/keel-trade.svg" alt="PyPI version"></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
<a href="https://usekeel.io/keel-mcp"><img src="https://img.shields.io/badge/product-keel--mcp-635BFF.svg" alt="Product page"></a>
<a href="https://glama.ai/mcp/servers/keel-trade/keel-trade"><img src="https://glama.ai/mcp/servers/keel-trade/keel-trade/badges/score.svg" alt="keel-trade MCP server"></a>
</p>
<p align="center">
<a href="https://usekeel.io">Website</a> ·
<a href="https://usekeel.io/keel-mcp">Product page</a> ·
<a href="https://usekeel.io/docs">Docs</a> ·
<a href="https://app.usekeel.io/share/gDXjURKqWPs8CZ4eXdqAI?ref=H0O2KN">Sample backtest</a> ·
<a href="https://github.com/keel-trade/keel-trade/discussions">Discussions</a>
</p>
---
## What is Keel?
[Keel](https://usekeel.io) is a quantitative crypto trading platform built around Hyperliquid — strategy development, backtesting, live execution, and portfolio management on the venue with the deepest on-chain perpetual order book. The full platform includes:
- A **web app** for composing strategies, running backtests, and deploying live ([app.usekeel.io](https://app.usekeel.io))
- A **deterministic backtest engine** with real Hyperliquid funding + price + slippage, walk-forward, and Monte Carlo
- **Bit-for-bit live execution** — the same compiled strategy artifact runs in backtest and on Hyperliquid
- A **strategy library** of documented, forkable trading strategies
- A **screener + calculator suite** at [usekeel.io/lab](https://usekeel.io/lab) (funding leaderboard, momentum, overfit-check, walk-forward visualizer, more)
- This package — `keel-trade` — the **agent-native research surface**
This repository is the public mirror of the `keel-trade` Python package: a single `pipx install` gives you both a CLI and a stdio MCP server, so the same tools work from a terminal or from any MCP-capable agent.
## Why agents create strategies, not trade them
Most agent-trading projects put an LLM in the execution loop. That makes systems slow, inconsistent, and hard to audit. Keel does the opposite:
```
You ──── compose ────► Strategy graph ──── compile ────► Deterministic artifact
▲ │
│ ▼
Agent edits Backtest engine
via MCP tools (real HL data)
│
▼
Live execution
(same artifact)
```
Three properties drive the design:
1. **Bit-for-bit parity between backtest and live.** Same compiled artifact, same engine, same data path. There is no second implementation that can drift.
2. **Typed composition over freeform code.** Strategies are graphs of versioned components. Compile errors catch bugs at author time instead of in production.
3. **Agents compose, the deterministic engine executes.** Claude / Cursor / Codex help you build the strategy. They are not in the trade loop.
## Choose your surface
`keel-trade` (this package) is the CLI + local MCP path. Keel is one product
with several places to use it — pick by where you are:
<!-- surface-routing:begin -->
<!-- GENERATED from shared/surface-routing.json — edit there, then run
python packages/keel-trade/keel-sdk/scripts/check_surface_routing.py --write -->
| You are… | Default path (shown first) | Also works |
| --- | --- | --- |
| Using Claude/ChatGPT on web or phone | Hosted endpoint — paste the URL (directory one-click coming) | CLI + local MCP |
| Working in Claude Code / Cursor / terminal | `pipx install keel-trade` (CLI + local MCP) | hosted endpoint |
| Going live with a strategy | Keel web app (connect account, review sizing, go live) | reads on every surface |
| Building your own agent/scripts | SDK + API key | CLI |
| Just browsing/running strategies | Web app + library | hosted endpoint |
<!-- surface-routing:end -->
- **Hosted endpoint** — the remote MCP at `https://mcp.usekeel.io/mcp`: one
23-tool research/backtest/read surface (compose, backtest, share, read-only
monitoring — no live-write, no local files). Paste the URL into any
remote-MCP client; the one-click directory listing is coming. Going live is
a handoff into the Keel web app.
- **CLI + local MCP** — this package (install below).
- **SDK + API key** — the [REST API](https://usekeel.io/docs/api-reference)
for building your own agents and scripts.
Per-surface zero-to-first-backtest runbook: [usekeel.io/agents](https://usekeel.io/agents).
## Install
### Claude Desktop — one-click (MCPB)
Download `keel-trade-<version>.mcpb` from the [latest release](https://github.com/keel-trade/keel-trade/releases/latest) and drag onto Claude Desktop. Cross-platform single bundle — works on macOS, Windows, and Linux.
The MCPB bundle requires system Python 3.11+ (same prerequisite as the terminal install path below). First launch takes ~10-30 seconds while the bundle pip-installs runtime deps to `~/.keel/mcpb-lib/py3.X/`; subsequent launches are instant.
### Terminal — pipx / uv (Claude Code, Codex, Cursor, Windsurf, etc.)
```bash
pipx install keel-trade
```
`uv tool install keel-trade` also works. Python 3.11+.
Then register the stdio MCP command with your agent host:
```bash
# Claude Code
claude mcp add keel -- keel mcp serve
# Codex
codex mcp add keel -- keel mcp serve
```
For Cursor, Windsurf, and generic MCP clients, see [usekeel.io/keel-mcp#install](https://usekeel.io/keel-mcp#install) or the [agent setup guide](https://usekeel.io/docs/sdk/agent-setup).
## First conversation with your agent
After install, sign in once via the agent (no terminal commands needed):
> **You:** _"Connect to Keel."_
>
> **Agent:** _Calls `keel_auth_login`. Browser opens to app.usekeel.io, you click Allow, tokens land in `~/.keel/config.yaml`. Authenticated for 30 days with transparent refresh._
Then describe what you want:
> **You:** _"Find me momentum signals for Hyperliquid top-30 perps and compose a backtest from 2024-08-15 to today."_
>
> **Agent:** _Calls `keel_components_search` → `keel_components_detail_batch` → `keel_strategy_compose` → `keel_backtest_run`. Returns a share URL with the full tearsheet (equity curve, Sharpe, max drawdown, per-asset attribution)._
Concrete example: [this share URL](https://app.usekeel.io/share/gDXjURKqWPs8CZ4eXdqAI?ref=H0O2KN) is a funding-carry backtest produced through exactly this flow — Sharpe 2.17 over 2024-08-15 → 2026-04-30 on real Hyperliquid data.
## What the MCP exposes
The default toolset spans status, auth, components, strategy lifecycle, backtest, audit, accounts, sharing, and read-only live monitoring. **Live-write tools** (`keel_live_deploy`, `keel_live_control`) require an explicit opt-in toolset plus a local arming step — agents can't deploy your account without you authorizing it twice.
Full per-tool reference: [usekeel.io/docs/sdk/tool-reference](https://usekeel.io/docs/sdk/tool-reference).
## CLI usage
Every MCP outcome tool has a CLI mirror. Useful for terminals, SSH sessions, CI, scripts, or agents that prefer subprocess calls:
```bash
# Auth + status
keel auth login
keel status
# Search components, compose, backtest
keel components search "momentum"
keel strategy compose --source-file my-strategy.py --dry-run
keel backtest run str_abc123 --start-date 2024-08-15 --wait
# Inspect a strategy
keel strategy get str_abc123
keel strategy log str_abc123
```
Full CLI reference: [usekeel.io/docs/sdk/cli-reference](https://usekeel.io/docs/sdk/cli-reference).
## What you can do with Keel
| Task | Surface |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Backtest a Hyperliquid strategy** — real fees, funding, slippage, ~220 perps | [usekeel.io/hyperliquid-backtest](https://usekeel.io/hyperliquid-backtest) |
| **Screen HL perps** — momentum, funding, volume, breakout, regime | [usekeel.io/lab](https://usekeel.io/lab) |
| **Use AI to build strategies** — typed composition, not freeform code | [usekeel.io/ai-trading-strategy-builder](https://usekeel.io/ai-trading-strategy-builder) |
| **Backtest portfolios** across the HL universe | [usekeel.io/crypto-portfolio-backtesting](https://usekeel.io/crypto-portfolio-backtesting) |
| **Robustness diagnostics** — walk-forward, Monte Carlo, deflated Sharpe, PBO | [usekeel.io/hyperliquid](https://usekeel.io/hyperliquid) |
| **Deploy a strategy live** on Hyperliquid (non-custodial) | [usekeel.io/strategy-os](https://usekeel.io/strategy-os) |
| **Compare strategies + venues** | [usekeel.io/compare](https://usekeel.io/compare) |
| **Browse documented trading strategies** | [usekeel.io/strategies](https://usekeel.io/strategies) |
## Documentation
- **Product page**: [usekeel.io/keel-mcp](https://usekeel.io/keel-mcp)
- **Getting started**: [usekeel.io/docs/getting-started](https://usekeel.io/docs/getting-started)
- **Agent setup (per host)**: [usekeel.io/docs/sdk/agent-setup](https://usekeel.io/docs/sdk/agent-setup)
- **CLI reference**: [usekeel.io/docs/sdk/cli-reference](https://usekeel.io/docs/sdk/cli-reference)
- **MCP tool reference**: [usekeel.io/docs/sdk/tool-reference](https://usekeel.io/docs/sdk/tool-reference)
- **REST API reference**: [usekeel.io/docs/api-reference](https://usekeel.io/docs/api-reference)
- **Agent instructions** (canonical, machine-readable): [`AGENTS.md`](AGENTS.md)
## Status
Alpha. The CLI and MCP surface are stable and ship to PyPI on a regular cadence; the underlying engine and component library are actively developed.
## How to contribute / report a bug
See [`CONTRIBUTING.md`](CONTRIBUTING.md). Short version:
- **Bug report** → open an issue using the bug template
- **Feature request, question, or pattern share** → use [Discussions](https://github.com/keel-trade/keel-trade/discussions)
- **Security issue** → email `team@usekeel.io` (do not open a public issue)
- **Patches** → PRs are welcome; we maintain in a private monorepo so PRs may take longer to land — see CONTRIBUTING for the porting process
## Related
- [Keel on Hyperliquid — the platform](https://usekeel.io)
- [What is MCP?](https://usekeel.io/learn/what-is-mcp)
- [AI agents on Hyperliquid — the definitive guide](https://usekeel.io/agent/hyperliquid)
- [Why we don't put LLMs in the trade loop](https://usekeel.io/learn/agentic-trading)
## License
MIT. See [`LICENSE`](LICENSE).
---
<p align="center">
Built by <a href="https://usekeel.io/about">the Keel Research Team</a> · <a href="https://x.com/usekeelio">@usekeelio</a>
</p>