hyperliquid-cli 0.1.0__tar.gz

hyperliquid_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv run --extra test pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

hyperliquid_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+data/trades.jsonl

hyperliquid_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tab55
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperliquid_cli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: hyperliquid-cli
+Version: 0.1.0
+Summary: Agent-first CLI for Hyperliquid trading
+Author: tab55
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,defi,hyperliquid,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: hyperliquid-python-sdk>=0.22.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: syrupy>=4.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# hyperliquid-cli
+
+Agent-first CLI for Hyperliquid perpetual futures trading. Thin Python wrapper over [hyperliquid-python-sdk](https://github.com/hyperliquid-x/hyperliquid-python-sdk).
+
+## Install
+
+```bash
+uv tool install hyperliquid-cli
+```
+
+## Usage
+
+```bash
+# Read commands (no auth needed)
+hl prices BTC ETH
+hl book BTC --depth 10
+hl assets TSLA
+hl funding BTC --history
+hl candles BTC 1h --limit 50
+
+# Account commands (needs HL_PRIVATE_KEY or --address)
+hl status
+hl balance
+hl positions
+hl orders
+hl fills
+
+# Write commands (needs HL_PRIVATE_KEY)
+hl order BTC buy 0.1 --market
+hl order BTC buy 0.1 95000 --tp 100000 --sl 90000
+hl cancel 77738308
+hl cancel-all BTC
+hl leverage BTC 10
+```
+
+## Auth
+
+Set `HL_PRIVATE_KEY` env var with your Hyperliquid API wallet key (can trade but cannot withdraw).
+
+Read-only commands work without auth using `--address`.
+
+## Design
+
+- JSON-only output (stdout), debug/warnings to stderr
+- Rich exit codes (0=success, 1=input, 2=auth, 3=API, 4=asset, 5=rejected)
+- Structured errors with recovery hints
+- Field projection via `--fields`
+- HIP-3 asset auto-resolution (e.g. `TSLA` → `xyz:TSLA`)
+- Trade logging to `data/trades.jsonl`
+
+## License
+
+MIT

hyperliquid_cli-0.1.0/README.md

@@ -0,0 +1,53 @@
+# hyperliquid-cli
+
+Agent-first CLI for Hyperliquid perpetual futures trading. Thin Python wrapper over [hyperliquid-python-sdk](https://github.com/hyperliquid-x/hyperliquid-python-sdk).
+
+## Install
+
+```bash
+uv tool install hyperliquid-cli
+```
+
+## Usage
+
+```bash
+# Read commands (no auth needed)
+hl prices BTC ETH
+hl book BTC --depth 10
+hl assets TSLA
+hl funding BTC --history
+hl candles BTC 1h --limit 50
+
+# Account commands (needs HL_PRIVATE_KEY or --address)
+hl status
+hl balance
+hl positions
+hl orders
+hl fills
+
+# Write commands (needs HL_PRIVATE_KEY)
+hl order BTC buy 0.1 --market
+hl order BTC buy 0.1 95000 --tp 100000 --sl 90000
+hl cancel 77738308
+hl cancel-all BTC
+hl leverage BTC 10
+```
+
+## Auth
+
+Set `HL_PRIVATE_KEY` env var with your Hyperliquid API wallet key (can trade but cannot withdraw).
+
+Read-only commands work without auth using `--address`.
+
+## Design
+
+- JSON-only output (stdout), debug/warnings to stderr
+- Rich exit codes (0=success, 1=input, 2=auth, 3=API, 4=asset, 5=rejected)
+- Structured errors with recovery hints
+- Field projection via `--fields`
+- HIP-3 asset auto-resolution (e.g. `TSLA` → `xyz:TSLA`)
+- Trade logging to `data/trades.jsonl`
+
+## License
+
+MIT

hyperliquid_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "hyperliquid-cli"
+version = "0.1.0"
+description = "Agent-first CLI for Hyperliquid trading"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "tab55" }]
+readme = "README.md"
+keywords = ["hyperliquid", "trading", "cli", "agent", "defi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "hyperliquid-python-sdk>=0.22.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0", "syrupy>=4.0"]
+
+[project.scripts]
+hl = "hl_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hl_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hyperliquid_cli-0.1.0/src/hl_cli/client.py

@@ -0,0 +1,68 @@
+"""SDK client factory — creates Info and Exchange instances."""
+
+import os
+
+import eth_account
+from hyperliquid.exchange import Exchange
+from hyperliquid.info import Info
+from hyperliquid.utils.constants import MAINNET_API_URL
+
+from hl_cli.output import die
+
+TESTNET_API_URL = "https://api.hyperliquid-testnet.xyz"
+
+
+def _base_url(testnet: bool) -> str:
+    return TESTNET_API_URL if testnet else MAINNET_API_URL
+
+
+def _get_key():
+    key = os.environ.get("HL_PRIVATE_KEY")
+    if not key:
+        die(
+            "auth_error",
+            "HL_PRIVATE_KEY environment variable not set",
+            hint="Set HL_PRIVATE_KEY to your API wallet private key",
+            exit_code=2,
+        )
+    return key
+
+
+def get_address(explicit: str = None) -> str:
+    """Get wallet address from explicit arg or HL_PRIVATE_KEY."""
+    if explicit:
+        return explicit
+    key = os.environ.get("HL_PRIVATE_KEY")
+    if key:
+        return eth_account.Account.from_key(key).address
+    die(
+        "auth_error",
+        "No address available",
+        hint="Set HL_PRIVATE_KEY or use --address",
+        exit_code=2,
+    )
+
+
+def get_info(testnet: bool = False) -> Info:
+    """Create Info client (default perps only, dexes loaded lazily by resolver)."""
+    return Info(_base_url(testnet), skip_ws=True)
+
+
+def get_exchange(testnet: bool = False) -> Exchange:
+    """Create Exchange client (requires HL_PRIVATE_KEY)."""
+    key = _get_key()
+    account = eth_account.Account.from_key(key)
+    return Exchange(account, _base_url(testnet), account_address=account.address)
+
+
+def get_all_mids(info: Info) -> dict:
+    """Get all mid prices including HIP-3 deployer assets."""
+    mids = info.all_mids()
+    try:
+        dex_list = info.post("/info", {"type": "perpDexs"})
+        for dex_info in dex_list[1:]:
+            dex_mids = info.post("/info", {"type": "allMids", "dex": dex_info["name"]})
+            mids.update(dex_mids)
+    except Exception:
+        pass
+    return mids

hyperliquid_cli-0.1.0/src/hl_cli/commands/act.py

@@ -0,0 +1,277 @@
+"""Act commands — order, cancel, cancel-all, leverage."""
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from hl_cli.client import get_address, get_exchange
+from hl_cli.main import app
+from hl_cli.output import die, format_timestamp, output
+from hl_cli.resolver import get_resolver
+
+SIDE_MAP = {"buy": True, "long": True, "sell": False, "short": False}
+
+
+def _parse_order_response(resp, asset: str, side_str: str, size: str):
+    """Parse SDK order response into CLI output format."""
+    if resp.get("status") == "err":
+        die("order_rejected", resp.get("response", str(resp)), exit_code=5)
+
+    data = resp.get("response", {}).get("data", {})
+    statuses = data.get("statuses", [])
+    if not statuses:
+        die("order_rejected", "No status in response", exit_code=5)
+
+    st = statuses[0]
+    if "error" in st:
+        die("order_rejected", st["error"], exit_code=5)
+
+    if "filled" in st:
+        filled = st["filled"]
+        return {
+            "status": "filled",
+            "oid": filled.get("oid", 0),
+            "asset": asset,
+            "side": side_str,
+            "size": filled.get("totalSz", size),
+            "avg_price": filled.get("avgPx", ""),
+        }
+    elif "resting" in st:
+        resting = st["resting"]
+        return {
+            "status": "resting",
+            "oid": resting.get("oid", 0),
+            "asset": asset,
+            "side": side_str,
+            "size": size,
+        }
+    else:
+        return {"status": "unknown", "raw": st}
+
+
+def _log_trade(result: dict, order_type: str, price: str = ""):
+    """Append trade record to data/trades.jsonl."""
+    trades_dir = Path("data")
+    trades_dir.mkdir(exist_ok=True)
+    record = {
+        "timestamp": format_timestamp(int(time.time() * 1000)),
+        "asset": result.get("asset", ""),
+        "side": result.get("side", ""),
+        "size": result.get("size", ""),
+        "price": result.get("avg_price", price),
+        "type": order_type,
+        "oid": result.get("oid", 0),
+        "status": result.get("status", ""),
+    }
+    with open(trades_dir / "trades.jsonl", "a") as f:
+        f.write(json.dumps(record, separators=(",", ":")) + "\n")
+
+
+@app.command()
+def order(
+    ctx: typer.Context,
+    asset: Annotated[str, typer.Argument(help="Asset name")],
+    side: Annotated[str, typer.Argument(help="buy/long or sell/short")],
+    size: Annotated[str, typer.Argument(help="Amount in base asset")],
+    price: Annotated[Optional[str], typer.Argument(help="Limit price")] = None,
+    market: Annotated[bool, typer.Option("--market", help="Market order (IOC)")] = False,
+    tif: Annotated[Optional[str], typer.Option("--tif", help="gtc|ioc|alo")] = None,
+    reduce_only: Annotated[bool, typer.Option("--reduce-only", help="Reduce only")] = False,
+    tp: Annotated[Optional[str], typer.Option("--tp", help="Take profit trigger price")] = None,
+    sl: Annotated[Optional[str], typer.Option("--sl", help="Stop loss trigger price")] = None,
+    cloid: Annotated[Optional[str], typer.Option("--cloid", help="Client order ID (hex)")] = None,
+):
+    """Place an order."""
+    opts = ctx.obj
+
+    side_lower = side.lower()
+    if side_lower not in SIDE_MAP:
+        die("input_error", f"Invalid side: {side}", hint="Use buy/long or sell/short")
+
+    is_buy = SIDE_MAP[side_lower]
+    sz = float(size)
+
+    exchange = get_exchange(opts["testnet"])
+    resolver = get_resolver(exchange.info)
+    resolved = resolver.resolve(asset)
+
+    from hyperliquid.utils.types import Cloid as SdkCloid
+    sdk_cloid = SdkCloid.from_str(cloid) if cloid else None
+
+    if market or price is None:
+        # Market order
+        resp = exchange.market_open(resolved, is_buy, sz, cloid=sdk_cloid)
+        result = _parse_order_response(resp, resolved, side_lower, size)
+        _log_trade(result, "market")
+        output(result, opts["fields"])
+        return
+
+    # Limit order
+    px = float(price)
+    tif_val = (tif or "gtc").capitalize()
+    if tif_val == "Gtc":
+        tif_val = "Gtc"
+    elif tif_val == "Ioc":
+        tif_val = "Ioc"
+    elif tif_val == "Alo":
+        tif_val = "Alo"
+    order_type = {"limit": {"tif": tif_val}}
+
+    if tp or sl:
+        # Parent + TP/SL as grouped order
+        order_requests = [
+            {
+                "coin": resolved,
+                "is_buy": is_buy,
+                "sz": sz,
+                "limit_px": px,
+                "order_type": order_type,
+                "reduce_only": reduce_only,
+                "cloid": sdk_cloid,
+            }
+        ]
+        if tp:
+            tp_type = {"trigger": {"triggerPx": float(tp), "isMarket": True, "tpsl": "tp"}}
+            order_requests.append({
+                "coin": resolved,
+                "is_buy": not is_buy,
+                "sz": sz,
+                "limit_px": float(tp),
+                "order_type": tp_type,
+                "reduce_only": True,
+            })
+        if sl:
+            sl_type = {"trigger": {"triggerPx": float(sl), "isMarket": True, "tpsl": "sl"}}
+            order_requests.append({
+                "coin": resolved,
+                "is_buy": not is_buy,
+                "sz": sz,
+                "limit_px": float(sl),
+                "order_type": sl_type,
+                "reduce_only": True,
+            })
+
+        resp = exchange.bulk_orders(
+            [exchange._order_request_to_wire(r) for r in order_requests]
+            if hasattr(exchange, "_order_request_to_wire")
+            else order_requests,
+            grouping="normalTpsl",
+        )
+        result = _parse_order_response(resp, resolved, side_lower, size)
+        _log_trade(result, "limit", price)
+        output(result, opts["fields"])
+    else:
+        resp = exchange.order(resolved, is_buy, sz, px, order_type, reduce_only, cloid=sdk_cloid)
+        result = _parse_order_response(resp, resolved, side_lower, size)
+        _log_trade(result, "limit", price)
+        output(result, opts["fields"])
+
+
+@app.command()
+def cancel(
+    ctx: typer.Context,
+    first: Annotated[str, typer.Argument(help="OID or asset name")],
+    second: Annotated[Optional[str], typer.Argument(help="OID (if first is asset)")] = None,
+    cloid: Annotated[Optional[str], typer.Option("--cloid", help="Cancel by client order ID")] = None,
+    asset_opt: Annotated[Optional[str], typer.Option("--asset", help="Asset for cloid cancel")] = None,
+):
+    """Cancel a specific order."""
+    opts = ctx.obj
+    exchange = get_exchange(opts["testnet"])
+
+    if cloid:
+        # Cancel by client order ID
+        if not asset_opt:
+            die("input_error", "Must specify --asset with --cloid", hint="hl cancel --cloid 0x... --asset BTC")
+        resolver = get_resolver(exchange.info)
+        resolved = resolver.resolve(asset_opt)
+        from hyperliquid.utils.types import Cloid as SdkCloid
+        resp = exchange.cancel_by_cloid(resolved, SdkCloid.from_str(cloid))
+        output({"status": "cancelled", "asset": resolved, "cloid": cloid}, opts["fields"])
+        return
+
+    if second is not None:
+        # hl cancel BTC 77738308
+        resolver = get_resolver(exchange.info)
+        resolved = resolver.resolve(first)
+        oid = int(second)
+        exchange.cancel(resolved, oid)
+        output({"status": "cancelled", "oid": oid, "asset": resolved}, opts["fields"])
+    else:
+        # hl cancel 77738308 — auto-lookup asset from open orders
+        oid = int(first)
+        addr = get_address()
+        open_orders = exchange.info.open_orders(addr)
+        coin = None
+        for o in open_orders:
+            if o["oid"] == oid:
+                coin = o["coin"]
+                break
+        if not coin:
+            die("input_error", f"Order {oid} not found in open orders", hint="Pass asset explicitly: hl cancel BTC {oid}")
+        exchange.cancel(coin, oid)
+        output({"status": "cancelled", "oid": oid, "asset": coin}, opts["fields"])
+
+
+@app.command(name="cancel-all")
+def cancel_all(
+    ctx: typer.Context,
+    asset: Annotated[Optional[str], typer.Argument(help="Cancel only this asset's orders")] = None,
+):
+    """Cancel all open orders."""
+    opts = ctx.obj
+    exchange = get_exchange(opts["testnet"])
+    addr = get_address()
+
+    open_orders = exchange.info.open_orders(addr)
+
+    if asset:
+        resolver = get_resolver(exchange.info)
+        resolved = resolver.resolve(asset)
+        open_orders = [o for o in open_orders if o["coin"] == resolved]
+
+    if not open_orders:
+        output({"cancelled": 0, "assets": []}, opts["fields"])
+        return
+
+    cancel_requests = [{"coin": o["coin"], "oid": o["oid"]} for o in open_orders]
+    exchange.bulk_cancel(cancel_requests)
+
+    assets_cancelled = sorted(set(o["coin"] for o in open_orders))
+    output({"cancelled": len(open_orders), "assets": assets_cancelled}, opts["fields"])
+
+
+@app.command()
+def leverage(
+    ctx: typer.Context,
+    asset: Annotated[str, typer.Argument(help="Asset name")],
+    lev: Annotated[int, typer.Argument(help="Leverage (integer)")],
+    cross: Annotated[bool, typer.Option("--cross", help="Cross margin")] = False,
+    isolated: Annotated[bool, typer.Option("--isolated", help="Isolated margin")] = False,
+):
+    """Set leverage for an asset."""
+    opts = ctx.obj
+
+    if cross and isolated:
+        die("input_error", "Cannot specify both --cross and --isolated")
+
+    exchange = get_exchange(opts["testnet"])
+    resolver = get_resolver(exchange.info)
+    resolved = resolver.resolve(asset)
+
+    is_cross = not isolated  # default is cross
+    if is_cross and ":" in resolved:
+        print("Warning: HIP-3 assets support isolated margin only. Using isolated.", file=sys.stderr)
+        is_cross = False
+
+    exchange.update_leverage(lev, resolved, is_cross)
+
+    output({
+        "asset": resolved,
+        "leverage": lev,
+        "margin_mode": "cross" if is_cross else "isolated",
+    }, opts["fields"])