Skip to main content

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 approve itself 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, 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.
  • 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.

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

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

Apache-2.0. See LICENSE and NOTICE.

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)

Source distribution for hl-guard 0.1.0
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)

Table of built distributions (wheels) for hl-guard 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page