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
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 approveitself and read the agent key. See 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,fillsandrisk_status. - Guarded write tools, only after you set up an agent key:
propose_order,close_position,cancel_order,haltandproposal_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.
- Out-of-band approval. With
approval: always, as in the example policy, every entry waits until you runhl-guard approve PROPOSAL_IDin a terminal and typeyes. No tool approves, and words in the chat are not an approval. - Closes and halt never wait.
close_positionandhaltonly 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 verifychecks the chain. - An agent key that you approve in your browser.
hl-guard initcreates 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.
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: a testnet setup, one rejected order, one approved order, a close and the ledger.
- Connect a client: Claude Desktop, Claude Code and Cursor.
- Write a policy: every limit and its ceiling.
- Threat model: who can do what, and what stops them.
Develop
You need uv.
uv sync --frozen
uv run hl-guard --version
uv run pytest -q
uv run pre-commit install
See CONTRIBUTING.md for the full set of checks.
License
Metadata
Release files for hl-guard 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hl_guard-0.1.0.tar.gz | 100.2 kB | With provenance | Details for hl_guard-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hl_guard-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for hl_guard-0.1.0-py3-none-any.whl |
Total release size: 218.7 kB
Release files / hl_guard-0.1.0.tar.gz
| Download URL | hl_guard-0.1.0.tar.gz |
|---|---|
| Size | 100.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dd0bd849e5ea18f9999a7b6580fb320e4d62354f87b599ce16fda32aa8adfce7
|
|
BLAKE2b-256 checksum How to use checksums |
7ef2c06389ad20cc220f60b2f294a6ef192ca3dd6c888e396c68a100df07c381
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / hl_guard-0.1.0-py3-none-any.whl
| Download URL | hl_guard-0.1.0-py3-none-any.whl |
|---|---|
| Size | 118.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11cd7d44eafed450cc4a08a6f249557e50cb8405ec955229eadb6e64f80c5bc5
|
|
BLAKE2b-256 checksum How to use checksums |
8d0cabc02d504f31284a74985f624ebaf63bc9f860f12c1d4193e31475231e70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for hl-guard 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hl_guard-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.