{"id":46749941,"url":"https://github.com/haturatu/hl","last_synced_at":"2026-03-13T00:01:14.016Z","repository":{"id":343093872,"uuid":"1166671837","full_name":"haturatu/hl","owner":"haturatu","description":"Hyperliquid CLI","archived":false,"fork":false,"pushed_at":"2026-03-09T22:09:33.000Z","size":157,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T00:32:47.575Z","etag":null,"topics":["hyperliquid","hyperliquid-dex"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haturatu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T13:33:41.000Z","updated_at":"2026-03-09T22:43:09.000Z","dependencies_parsed_at":"2026-03-13T00:00:53.857Z","dependency_job_id":null,"html_url":"https://github.com/haturatu/hl","commit_stats":null,"previous_names":["haturatu/hl"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/haturatu/hl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haturatu%2Fhl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haturatu%2Fhl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haturatu%2Fhl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haturatu%2Fhl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haturatu","download_url":"https://codeload.github.com/haturatu/hl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haturatu%2Fhl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30450872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hyperliquid","hyperliquid-dex"],"created_at":"2026-03-09T20:33:51.478Z","updated_at":"2026-03-13T00:01:14.008Z","avatar_url":"https://github.com/haturatu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Hyperliquid CLI (Python)](#hyperliquid-cli-python)\n  - [Setup](#setup)\n    - [Requirements](#requirements)\n    - [Installation](#installation)\n    - [Bash Completion](#bash-completion)\n  - [CLI Basics](#cli-basics)\n    - [Global Options](#global-options)\n    - [Supported Commands](#supported-commands)\n    - [Configuration](#configuration)\n    - [Security Notes](#security-notes)\n  - [Development](#development)\n    - [Run for Development](#run-for-development)\n    - [JSON Pattern Tests](#json-pattern-tests)\n  - [Order Features](#order-features)\n    - [TWAP Orders](#twap-orders)\n    - [Stake-Based Orders](#stake-based-orders)\n  - [Project](#project)\n    - [Acknowledgments](#acknowledgments)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# Hyperliquid CLI (Python)\n\nPython CLI for Hyperliquid account management, market data, and order execution.\n\n## Setup\n\n### Requirements\n\n- Python 3.10+\n- `hyperliquid-python-sdk` for API interactions\n- `rich` for pretty console output\n- `eth-account` for key management\n- Optional: `make` for installation and uninstallation scripts\n\n### Installation\n\nInstall from git and also set up Bash completion with `make install`:\n\n```bash\ngit clone https://github.com/haturatu/hl.git\ncd hl\nmake install\n```\n\nInstall from source for local development:\n\n```bash\ncd hl\npython3 -m pip install --user -e .\n```\n\nInstall from PyPI:\n\n```bash\npip install --user hyperliquid-cli-python\n```\n\nAfter installation, the `hl` command is available:\n\n```bash\nhl --help\n```\n\n### Bash Completion\n\n`hl` can print a Bash completion script for top-level commands and subcommands.\n\nNote: `pip install -e .` and `pip install hyperliquid-cli-python` install the\n`hl` command, but they do not automatically enable Bash completion.\n\nEnable it for the current shell:\n\n```bash\neval \"$(hl completion bash)\"\n```\n\nPersist it in `~/.bashrc`:\n\n```bash\necho 'eval \"$(hl completion bash)\"' \u003e\u003e ~/.bashrc\n```\n\nIf you want the old helper flow that also edits `~/.bashrc`, `make install`\nstill exists.\n\nTo remove the package and any managed `~/.bashrc` completion line:\n\n```bash\nmake uninstall\n```\n\n## CLI Basics\n\n```bash\n$ hl --help\nusage: hl [-h] [--json] [--testnet] {account,order,asset,markets,referral,completion} ...\n\nCLI for Hyperliquid DEX\n\npositional arguments:\n  {account,order,asset,markets,referral,completion}\n    account             Account management and information\n    order               Order management and trading\n    asset               Asset-specific information\n    markets             Market information\n    referral            Referral management\n    completion          Print shell completion script\n\noptions:\n  -h, --help            show this help message and exit\n  --json                Output in JSON format\n  --testnet             Use testnet\n\nCommand tree:\n  account add|ls|set-default|remove|positions|orders|balances|portfolio\n  order ls|limit|market|tpsl|twap|twap-cancel|cancel|cancel-all|set-leverage|configure\n  asset price|book|leverage\n  markets ls\n  referral set|status\nExamples:\n  hl account add\n  hl order twap buy 1 BTC 30 --randomize\n  hl order twap-cancel BTC 12345\n  hl account positions --watch\n```\n\n### Global Options\n\n- `--json` Output JSON\n- `--testnet` Use testnet\n\n### Supported Commands\n\n- `hl account add|ls|set-default|remove`\n- `hl account positions|orders|balances|portfolio`\n- `hl order ls|limit|market|tpsl|twap|twap-cancel|cancel|cancel-all|set-leverage|configure`\n- `hl asset price|book|leverage`\n- `hl markets ls|search`\n- `hl referral set|status`\n\n### Configuration\n\n- DB: `~/.hl/hl.db`\n- Order config: `~/.hl/order-config.json`\n\nEnvironment variable fallback (when DB account is not configured):\n\n- `HYPERLIQUID_PRIVATE_KEY`\n- `HYPERLIQUID_WALLET_ADDRESS`\n\n### Security Notes\n\nAccount data stored in `~/.hl/hl.db` is encrypted at rest for these fields:\n\n- `user_address`\n- `api_wallet_public_key`\n- `api_wallet_private_key`\n\nThe current implementation derives a 32-byte key as follows:\n\n1. Resolve the command path used to run `hl`\n2. Hash that path with SHA-256\n3. Use the resulting digest as the ChaCha20 key\n\nEach stored value is encrypted independently with its own random nonce.\n\nThis means:\n\n- the same installed command path can transparently decrypt the saved values\n- changing the executable path can make existing saved account data undecryptable\n- this is path-bound encryption, not password-based encryption\n\nExample:\n\n```bash\n$ which hl\n/home/haturatu/.local/bin/hl\n```\n\nIf `hl` is installed at a user-local path like `/home/haturatu/.local/bin/hl`, then\nthe encryption key is effectively tied to that installed command path. In normal usage,\nthat often behaves like \"the user who has this `hl` on their path can decrypt the DB\".\nSo in practice it can look close to per-user decryption when each user has their own\nhome directory and their own local install path.\n\nImportant limitation:\n\n- this mechanism does **not** prove OS user identity by itself\n- if another OS user can both read `~/.hl/hl.db` and execute the same `hl` binary\n  path, path-based derivation alone does not prevent that user from decrypting the data\n\nSo this mechanism is mainly useful as a coupling between the saved DB contents and the\nspecific installed command path. It helps prevent casual reuse of the DB from a different\nbinary location, but it is not a substitute for filesystem permissions or disk encryption.\n\nEnvironment variable fallback still exists when DB account data is not configured:\n\n- `HYPERLIQUID_PRIVATE_KEY`\n- `HYPERLIQUID_WALLET_ADDRESS`\n\nThese environment variables are not stored in the encrypted DB. They are read as\nplain process environment values at runtime.\n\nPractical guidance:\n\n- Use wallets or API keys that would not be catastrophic if leaked\n- Restrict which OS user can run this tool\n- If you need stronger protection, use disk encryption as the higher-level control\n\n## Development\n\n### Run for Development\n\n```bash\ncd hl\nPYTHONPATH=src python -m hl_cli.cli.argparse_main --help\n```\n\n### JSON Pattern Tests\n\n`tests/` validates that every subcommand pattern produces parseable raw JSON output in `--json` mode.\n\n```bash\ncd hl\nPYTHONPATH=src python -m unittest -v tests.test_json_patterns\n```\n\n## Order Features\n\nOrder side semantics:\n\n- `buy` / `sell` are for spot markets\n- `long` / `short` are for perp markets\n- `close` is for closing an open perp position\n\n### TWAP Orders\n\n`hyperliquid-python-sdk` does not provide a high-level TWAP method, so this CLI signs and submits the official\n`exchange` actions `twapOrder` / `twapCancel`. Successful submissions store the returned `twapId`\nlocally under `~/.hl/twap_orders.json` so the CLI can show and cancel tracked TWAPs later.\n\nTWAP is perp-only, so use `long` / `short`.\n\n```bash\n# 30-minute native TWAP\nhl order twap long 1.0 BTC 30\n\n# Derive total TWAP size from USD margin (stake * leverage)\nhl order twap long 0 BTC 30 --stake 5\n\n# Compatibility format: 5,10 is sent as total 50 minutes\nhl order twap short 2.0 ETH 5,10 --randomize\n\n# Cancel TWAP\nhl order twap-cancel BTC 12345\n\n# Or list tracked active TWAPs and pick one interactively\nhl order twap-cancel\n```\n\n### Stake-Based Orders\n\n`--stake` is used by the CLI to derive order size.\n\nMode-specific behavior:\n\n- `buy` / `sell` derive spot order size\n- `long` / `short` derive perp order size\n- `--leverage`, `--cross`, `--isolated`, and `--reduce-only` are only supported with `long` / `short`\n\n- If you pass `--stake 50 --leverage 20`, the CLI derives size from about `$1000`\n  of notional (`50 * 20`).\n- If you pass `--stake 50` without `--leverage`, the CLI derives size from about\n  `$50` of notional.\n\nImportant: omitting `--leverage` does **not** mean your account or position is forced\nto `1x`. It only means the CLI does not multiply `--stake` by leverage when calculating\nthe order size. If the exchange/account already has leverage set for that asset, the\nresulting position can still show that existing leverage in `hl account positions`.\n\nThis means:\n\n- `--stake 50` means the CLI sizes the order from about `$50` of notional\n- `--stake 50 --leverage 20` means about `$1000` of position notional\n\nSo:\n\n- `--leverage` changes how `--stake` is converted into order size\n- existing leverage on the exchange can still affect margin usage and the leverage\n  shown later in `hl account positions`\n\n```bash\n# Spot buy: CLI sizes the order from about $50 of spot notional\nhl order market buy @142 --stake 50\n\n# Spot sell: CLI sizes the order from about $50 of spot notional\nhl order market sell @142 --stake 50\n\n# Perp long with leverage 20: CLI sizes the order from about $1,000 of BTC notional\nhl order limit long BTC 65000 --stake 50 --leverage 20 --cross\n\n# Perp long with leverage 20: CLI sizes the order from about $1,000 of BTC notional\nhl order market long BTC --stake 50 --leverage 20 --isolated\n\n# Example:\n# BTC at 69,000\n# - --stake 50                 =\u003e about 0.000724 BTC of order size\n# - --stake 50 --leverage 20   =\u003e about 0.01449 BTC\n#\n# ETH at 2,020\n# - --stake 50                 =\u003e about 0.02475 ETH of order size\n# - --stake 50 --leverage 20   =\u003e about 0.2475 ETH\n\n# Set leverage and margin mode at order time\nhl order limit long BTC 65000 --stake 50 --leverage 20 --cross\nhl order market long BTC --stake 50 --leverage 20 --isolated\n\n# Set leverage directly\nhl order set-leverage BTC 20 --cross\n\n# If leverage is invalid, show warning and retry with coin maxLeverage from /info type=meta\nhl order set-leverage BTC 60\n\n# Close full position by coin\nhl order market close ETH\nhl order market close xyz:TSLA\n\n# Close 50% of a position\nhl order market close ETH --ratio 0.5\n\n# Set TP/SL trigger orders for an open position\nhl order tpsl ETH --tp 1900 --sl 1800\nhl order tpsl ETH --sl 1800 --ratio 0.5\n```\n\n## Project\n\n### Acknowledgments\n\n- https://app.hyperliquid.xyz/\n- https://github.com/chrisling-dev/hyperliquid-cli\n- https://github.com/ehfuzzz/hyperliquid-CLI\n\nThis project is primarily a Python implementation of\nhttps://github.com/chrisling-dev/hyperliquid-cli.\nSome features, including the TWAP order implementation, are also based on ideas from\nhttps://github.com/ehfuzzz/hyperliquid-CLI.\n\nThis repository also includes changes such as expanded `order` subcommands, the\n`--stake` option, and additional `market` subcommand functionality.\n\nAt the moment, I am not fully sure how this should be handled from a licensing and\nattribution perspective, so this repository is being published under my BSD 2-Clause\nLicense as a temporary choice. If you have a better idea for the appropriate license\nnotice or attribution, please open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaturatu%2Fhl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaturatu%2Fhl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaturatu%2Fhl/lists"}