Metadata-Version: 2.4
Name: hl-guard
Version: 0.1.0
Summary: A self-hosted MCP server that guards Hyperliquid orders with a user policy.
Author: Ihor Solopii
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: coincurve>=20,<22
Requires-Dist: eth-account>=0.13.7,<0.14
Requires-Dist: mcp==2.3.0
Requires-Dist: msgpack>=1.1,<2
Requires-Dist: pyyaml>=6.0.3,<7
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# hl-guard

hl-guard is a self-hosted MCP server for Hyperliquid perpetuals. An MCP client,
such as Claude Desktop, Claude Code or Cursor, can read markets and propose
orders through it. The server, not the model, decides whether an order goes
out. It checks every proposal against a policy file that you write and that no
tool can change, and it records every step in a hash-chained ledger.

hl-guard is a safety layer. It limits how much a wrong, confused or steered
model can do with your account. It does not make a strategy profitable, and
this project makes no claim about returns.

## What hl-guard does not do

> [!IMPORTANT]
> **hl-guard does not place stop-loss or take-profit orders.** Every entry must
> name a stop-loss price, and the risk gate checks it, but hl-guard only
> records that price in the ledger and shows it to you. It does not send it to
> the exchange. After an entry fills, you or the model must place the stop,
> for example in the Hyperliquid app. Until then the position has no stop on
> the exchange.

hl-guard also does not:

- move funds. It has no withdraw or transfer tool, and it never builds a
  withdrawal, transfer, vault or sub-account action for the agent key to sign.
- trade spot, open cross-margin positions, or go above 5x leverage.
- take an approval from the chat. You approve in a terminal with
  `hl-guard approve`.
- protect you from a client that can run shell commands as your user. Such a
  client can run `hl-guard approve` itself and read the agent key. See
  [SECURITY.md](SECURITY.md).
- run as a hosted service. It runs on your machine only.

## What it does

- **Read tools.** `markets`, `order_book`, `candles`, `account`, `positions`,
  `open_orders`, `fills` and `risk_status`.
- **Guarded write tools**, only after you set up an agent key:
  `propose_order`, `close_position`, `cancel_order`, `halt` and
  `proposal_status`.
- **A risk gate.** Every entry passes the limits in your policy: coins, size
  per order, total exposure, leverage, open orders, entries per day, cooldown
  per coin, daily loss, loss streak, a required stop-loss, a price band around
  the mark and a fresh account read. Product hard ceilings bound every limit.
  See [docs/policy.md](docs/policy.md).
- **Out-of-band approval.** With `approval: always`, as in the example
  policy, every entry waits until you run
  `hl-guard approve PROPOSAL_ID` in a terminal and type `yes`. No tool approves, and
  words in the chat are not an approval.
- **Closes and halt never wait.** `close_position` and `halt` only reduce
  risk, so they need no approval.
- **A ledger.** Every proposal, decision, order and exchange answer, and
  every fill of an order hl-guard placed, goes on a line in an append-only
  file with a SHA-256 hash chain.
  `hl-guard ledger verify` checks the chain.
- **An agent key that you approve in your browser.** `hl-guard init` creates a
  local trading key and serves a local page where your browser wallet
  approves it. The approval expires after 1 to 180 days, 30 by default.
- **Testnet first.** The default network is the Hyperliquid testnet. Mainnet
  needs a mode file and a start flag. See [docs/policy.md](docs/policy.md).

## Status

Pre-alpha, version 0.1.0. Test it on the Hyperliquid testnet before you point
it at real funds. Expect breaking changes.

## Get started

- [Quick start](docs/quickstart.md): a testnet setup, one rejected order, one
  approved order, a close and the ledger.
- [Connect a client](docs/clients.md): Claude Desktop, Claude Code and Cursor.
- [Write a policy](docs/policy.md): every limit and its ceiling.
- [Threat model](docs/threat-model.md): who can do what, and what stops them.

## Develop

You need [uv](https://docs.astral.sh/uv/).

```sh
uv sync --frozen
uv run hl-guard --version
uv run pytest -q
uv run pre-commit install
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full set of checks.

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
