hyperliquid-cli 0.1.0__py3-none-any.whl

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

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"])

hl_cli/commands/orient.py

@@ -0,0 +1,174 @@
+"""Orient commands — status, balance, positions, orders."""
+
+from typing import Annotated, Optional
+
+import typer
+
+from hl_cli.client import get_address, get_all_mids, get_info
+from hl_cli.main import app
+from hl_cli.output import format_timestamp, output
+from hl_cli.resolver import get_resolver
+
+
+@app.command()
+def status(
+    ctx: typer.Context,
+    address: Annotated[Optional[str], typer.Option("--address", help="Check another address")] = None,
+):
+    """One-shot account overview: balance + positions + open orders."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    addr = get_address(address)
+
+    state = info.user_state(addr)
+    orders = info.frontend_open_orders(addr)
+    mids = get_all_mids(info)
+
+    margin = state.get("crossMarginSummary", state.get("marginSummary", {}))
+
+    positions = []
+    for p in state.get("assetPositions", []):
+        pos = p["position"]
+        size = float(pos["szi"])
+        if size == 0:
+            continue
+        coin = pos["coin"]
+        lev = pos["leverage"]
+        positions.append({
+            "asset": coin,
+            "side": "long" if size > 0 else "short",
+            "size": str(abs(size)),
+            "entry_price": pos["entryPx"],
+            "mark_price": mids.get(coin, ""),
+            "unrealized_pnl": pos["unrealizedPnl"],
+            "liquidation_price": pos.get("liquidationPx", ""),
+            "leverage": str(lev["value"]) if isinstance(lev, dict) else str(lev),
+            "margin_used": pos["marginUsed"],
+        })
+
+    order_list = []
+    for o in orders:
+        order_list.append({
+            "oid": o["oid"],
+            "asset": o["coin"],
+            "side": "buy" if o["side"] == "B" else "sell",
+            "price": o["limitPx"],
+            "size": o["sz"],
+            "type": (o.get("orderType") or "Limit").lower(),
+            "tif": (o.get("tif") or "").lower() or None,
+            "reduce_only": o.get("reduceOnly", False),
+            "timestamp": format_timestamp(o.get("timestamp", 0)),
+        })
+
+    result = {
+        "account_value": margin.get("accountValue", "0"),
+        "withdrawable": state.get("withdrawable", "0"),
+        "total_margin_used": margin.get("totalMarginUsed", "0"),
+        "total_ntl_pos": margin.get("totalNtlPos", "0"),
+        "positions": positions,
+        "open_orders": order_list,
+    }
+    output(result, opts["fields"])
+
+
+@app.command()
+def balance(
+    ctx: typer.Context,
+    address: Annotated[Optional[str], typer.Option("--address", help="Check another address")] = None,
+):
+    """Account balance."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    addr = get_address(address)
+
+    state = info.user_state(addr)
+    margin = state.get("crossMarginSummary", state.get("marginSummary", {}))
+
+    result = {
+        "account_value": margin.get("accountValue", "0"),
+        "total_margin_used": margin.get("totalMarginUsed", "0"),
+        "total_ntl_pos": margin.get("totalNtlPos", "0"),
+        "withdrawable": state.get("withdrawable", "0"),
+    }
+    output(result, opts["fields"])
+
+
+@app.command()
+def positions(
+    ctx: typer.Context,
+    asset: Annotated[Optional[str], typer.Argument(help="Filter by asset")] = None,
+    address: Annotated[Optional[str], typer.Option("--address", help="Check another address")] = None,
+):
+    """Open positions with P&L."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    addr = get_address(address)
+
+    state = info.user_state(addr)
+    mids = get_all_mids(info)
+
+    resolved = None
+    if asset:
+        resolver = get_resolver(info)
+        resolved = resolver.resolve(asset)
+
+    result = []
+    for p in state.get("assetPositions", []):
+        pos = p["position"]
+        size = float(pos["szi"])
+        if size == 0:
+            continue
+        coin = pos["coin"]
+        if resolved and coin != resolved:
+            continue
+        lev = pos["leverage"]
+        result.append({
+            "asset": coin,
+            "side": "long" if size > 0 else "short",
+            "size": str(abs(size)),
+            "entry_price": pos["entryPx"],
+            "mark_price": mids.get(coin, ""),
+            "unrealized_pnl": pos["unrealizedPnl"],
+            "liquidation_price": pos.get("liquidationPx", ""),
+            "leverage": str(lev["value"]) if isinstance(lev, dict) else str(lev),
+            "margin_used": pos["marginUsed"],
+        })
+
+    output(result, opts["fields"])
+
+
+@app.command()
+def orders(
+    ctx: typer.Context,
+    asset: Annotated[Optional[str], typer.Argument(help="Filter by asset")] = None,
+):
+    """Open/pending orders."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    addr = get_address()
+
+    raw = info.frontend_open_orders(addr)
+
+    resolved = None
+    if asset:
+        resolver = get_resolver(info)
+        resolved = resolver.resolve(asset)
+
+    result = []
+    for o in raw:
+        coin = o["coin"]
+        if resolved and coin != resolved:
+            continue
+        result.append({
+            "oid": o["oid"],
+            "asset": coin,
+            "side": "buy" if o["side"] == "B" else "sell",
+            "price": o["limitPx"],
+            "size": o["sz"],
+            "type": (o.get("orderType") or "Limit").lower(),
+            "tif": (o.get("tif") or "").lower() or None,
+            "reduce_only": o.get("reduceOnly", False),
+            "timestamp": format_timestamp(o.get("timestamp", 0)),
+        })
+
+    output(result, opts["fields"])

hl_cli/commands/research.py

@@ -0,0 +1,287 @@
+"""Research commands — assets, prices, book, funding, candles."""
+
+import time
+from typing import Annotated, List, Optional
+
+import typer
+
+from hl_cli.client import get_all_mids, get_info
+from hl_cli.main import app
+from hl_cli.output import (
+    die,
+    format_timestamp,
+    interval_to_ms,
+    output,
+    parse_time,
+)
+from hl_cli.resolver import get_resolver
+
+
+@app.command()
+def assets(
+    ctx: typer.Context,
+    query: Annotated[Optional[str], typer.Argument(help="Search by name")] = None,
+    deployer: Annotated[Optional[str], typer.Option("--deployer", help="Filter by deployer")] = None,
+    sort: Annotated[str, typer.Option("--sort", help="Sort: volume|oi|name")] = "volume",
+):
+    """List and search all tradeable perps."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+
+    # Default perps with full context (volume, OI, funding, etc.)
+    meta_ctxs = info.meta_and_asset_ctxs()
+    meta = meta_ctxs[0]
+    ctxs = meta_ctxs[1]
+
+    result = []
+    for i, (asset_info, asset_ctx) in enumerate(zip(meta["universe"], ctxs)):
+        result.append({
+            "asset": asset_info["name"],
+            "asset_id": i,
+            "max_leverage": asset_info.get("maxLeverage", 0),
+            "mark_price": asset_ctx.get("markPx", ""),
+            "funding_rate": asset_ctx.get("funding", ""),
+            "open_interest": asset_ctx.get("openInterest", ""),
+            "volume_24h": asset_ctx.get("dayNtlVlm", ""),
+        })
+
+    # HIP-3 assets — load dex metadata and try to get contexts
+    try:
+        dex_list = info.post("/info", {"type": "perpDexs"})
+        mids = get_all_mids(info)
+
+        for idx, dex_info in enumerate(dex_list[1:]):
+            dex_name = dex_info["name"]
+            try:
+                # Try metaAndAssetCtxs with dex param for full data
+                dex_data = info.post("/info", {"type": "metaAndAssetCtxs", "dex": dex_name})
+                dex_meta = dex_data[0]
+                dex_ctxs = dex_data[1]
+                offset = 110000 + idx * 10000
+
+                for j, (ai, ac) in enumerate(zip(dex_meta["universe"], dex_ctxs)):
+                    name = ai["name"]
+                    result.append({
+                        "asset": name,
+                        "asset_id": j + offset,
+                        "deployer": dex_name,
+                        "max_leverage": ai.get("maxLeverage", 0),
+                        "mark_price": ac.get("markPx", mids.get(name, "")),
+                        "funding_rate": ac.get("funding", ""),
+                        "open_interest": ac.get("openInterest", ""),
+                        "volume_24h": ac.get("dayNtlVlm", ""),
+                    })
+            except Exception:
+                # Fallback: use meta only + all_mids for price
+                try:
+                    dex_meta = info.meta(dex=dex_name)
+                    for ai in dex_meta["universe"]:
+                        name = ai["name"]
+                        result.append({
+                            "asset": name,
+                            "deployer": dex_name,
+                            "max_leverage": ai.get("maxLeverage", 0),
+                            "mark_price": mids.get(name, ""),
+                            "funding_rate": "",
+                            "open_interest": "",
+                            "volume_24h": "",
+                        })
+                except Exception:
+                    continue
+    except Exception:
+        pass  # no HIP-3 data available
+
+    # Filter
+    if query:
+        q = query.upper()
+        result = [a for a in result if q in a["asset"].upper()]
+    if deployer:
+        result = [a for a in result if a.get("deployer", "") == deployer]
+
+    # Sort
+    sort_key = {"volume": "volume_24h", "oi": "open_interest", "name": "asset"}.get(sort, "volume_24h")
+    if sort_key == "asset":
+        result.sort(key=lambda x: x["asset"])
+    else:
+        result.sort(key=lambda x: float(x.get(sort_key) or "0"), reverse=True)
+
+    output(result, opts["fields"])
+
+
+@app.command()
+def prices(
+    ctx: typer.Context,
+    assets: Annotated[Optional[List[str]], typer.Argument(help="Asset names")] = None,
+):
+    """Current prices."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+
+    if not assets:
+        # Lightweight: all mid prices (including HIP-3)
+        mids = get_all_mids(info)
+        result = [{"asset": k, "mid": v} for k, v in sorted(mids.items()) if not k.startswith("@")]
+        output(result, opts["fields"])
+        return
+
+    # Detailed: per-asset info
+    resolver = get_resolver(info)
+    mids = get_all_mids(info)
+
+    # Build context lookup from default perps + HIP-3 dexes
+    meta_ctxs = info.meta_and_asset_ctxs()
+    ctx_lookup = {}
+    for asset_info, asset_ctx in zip(meta_ctxs[0]["universe"], meta_ctxs[1]):
+        ctx_lookup[asset_info["name"]] = asset_ctx
+
+    # Load HIP-3 context for any HIP-3 assets requested
+    hip3_dexes_needed = set()
+    for name in assets:
+        resolved = resolver.resolve(name)
+        if ":" in resolved and resolved not in ctx_lookup:
+            hip3_dexes_needed.add(resolved.split(":")[0])
+    for dex in hip3_dexes_needed:
+        try:
+            dex_data = info.post("/info", {"type": "metaAndAssetCtxs", "dex": dex})
+            for ai, ac in zip(dex_data[0]["universe"], dex_data[1]):
+                ctx_lookup[ai["name"]] = ac
+        except Exception:
+            pass
+
+    result = []
+    for name in assets:
+        resolved = resolver.resolve(name)
+        ac = ctx_lookup.get(resolved, {})
+        mid = mids.get(resolved, "")
+        prev = ac.get("prevDayPx", "")
+        change = ""
+        if mid and prev:
+            try:
+                change = f"{(float(mid) / float(prev) - 1) * 100:.2f}"
+            except (ValueError, ZeroDivisionError):
+                pass
+        result.append({
+            "asset": resolved,
+            "mid": mid,
+            "mark": ac.get("markPx", mid),
+            "oracle": ac.get("oraclePx", ""),
+            "prev_day": prev,
+            "change_pct": change,
+        })
+
+    output(result, opts["fields"])
+
+
+@app.command()
+def book(
+    ctx: typer.Context,
+    asset: Annotated[str, typer.Argument(help="Asset name")],
+    depth: Annotated[int, typer.Option("--depth", help="Levels per side (max 20)")] = 5,
+):
+    """Order book depth."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    resolver = get_resolver(info)
+    resolved = resolver.resolve(asset)
+
+    snapshot = info.l2_snapshot(resolved)
+    levels = snapshot.get("levels", [[], []])
+
+    bids = [{"price": lv["px"], "size": lv["sz"], "orders": lv["n"]} for lv in levels[0][:depth]]
+    asks = [{"price": lv["px"], "size": lv["sz"], "orders": lv["n"]} for lv in levels[1][:depth]]
+
+    result = {"asset": resolved, "bids": bids, "asks": asks}
+    output(result, opts["fields"])
+
+
+@app.command()
+def funding(
+    ctx: typer.Context,
+    assets: Annotated[Optional[List[str]], typer.Argument(help="Asset names")] = None,
+    history: Annotated[bool, typer.Option("--history", help="Show historical rates")] = False,
+    limit: Annotated[int, typer.Option("--limit", help="Number of periods")] = 20,
+    start: Annotated[Optional[str], typer.Option("--start", help="Start time (ISO 8601)")] = None,
+    end: Annotated[Optional[str], typer.Option("--end", help="End time (ISO 8601)")] = None,
+):
+    """Funding rates (current or historical)."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+
+    if history:
+        if not assets:
+            die("input_error", "Specify at least one asset for --history", hint="hl funding BTC --history")
+        resolver = get_resolver(info)
+        result = []
+        for name in assets:
+            resolved = resolver.resolve(name)
+            start_ms = parse_time(start) if start else int(time.time() * 1000) - limit * 8 * 3600 * 1000
+            end_ms = parse_time(end) if end else None
+            data = info.funding_history(resolved, start_ms, end_ms)
+            for h in data[-limit:]:
+                rate = h.get("fundingRate", "0")
+                result.append({
+                    "asset": resolved,
+                    "rate": rate,
+                    "premium": h.get("premium", ""),
+                    "annualized": f"{float(rate) * 3 * 365:.2f}",
+                    "time": format_timestamp(h.get("time", 0)),
+                })
+        output(result, opts["fields"])
+    else:
+        # Current rates from metaAndAssetCtxs
+        meta_ctxs = info.meta_and_asset_ctxs()
+        asset_filter = {a.upper() for a in assets} if assets else None
+
+        result = []
+        for asset_info, asset_ctx in zip(meta_ctxs[0]["universe"], meta_ctxs[1]):
+            name = asset_info["name"]
+            if asset_filter and name.upper() not in asset_filter:
+                continue
+            rate = asset_ctx.get("funding", "0")
+            result.append({
+                "asset": name,
+                "rate": rate,
+                "premium": asset_ctx.get("premium", ""),
+                "annualized": f"{float(rate) * 3 * 365:.2f}",
+            })
+
+        output(result, opts["fields"])
+
+
+@app.command()
+def candles(
+    ctx: typer.Context,
+    asset: Annotated[str, typer.Argument(help="Asset name")],
+    interval: Annotated[str, typer.Argument(help="1m 5m 15m 1h 4h 1d etc.")],
+    limit: Annotated[int, typer.Option("--limit", help="Number of candles (max 5000)")] = 100,
+    start: Annotated[Optional[str], typer.Option("--start", help="Start time (ISO 8601)")] = None,
+    end: Annotated[Optional[str], typer.Option("--end", help="End time (ISO 8601)")] = None,
+):
+    """OHLCV price history."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    resolver = get_resolver(info)
+    resolved = resolver.resolve(asset)
+
+    end_ms = parse_time(end) if end else int(time.time() * 1000)
+    if start:
+        start_ms = parse_time(start)
+    else:
+        ms_per = interval_to_ms(interval)
+        start_ms = end_ms - ms_per * limit
+
+    data = info.candles_snapshot(resolved, interval, start_ms, end_ms)
+
+    result = []
+    for c in data[-limit:]:
+        result.append({
+            "time": format_timestamp(c["t"]),
+            "open": c["o"],
+            "high": c["h"],
+            "low": c["l"],
+            "close": c["c"],
+            "volume": c["v"],
+            "trades": c["n"],
+        })
+
+    output(result, opts["fields"])

hl_cli/commands/review.py

@@ -0,0 +1,84 @@
+"""Review commands — fills, trades."""
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from hl_cli.client import get_address, get_info
+from hl_cli.main import app
+from hl_cli.output import format_timestamp, output, parse_time
+from hl_cli.resolver import get_resolver
+
+
+@app.command()
+def fills(
+    ctx: typer.Context,
+    asset: Annotated[Optional[str], typer.Argument(help="Filter by asset")] = None,
+    limit: Annotated[int, typer.Option("--limit", help="Number of fills (max 2000)")] = 20,
+    start: Annotated[Optional[str], typer.Option("--start", help="Start time (ISO 8601)")] = None,
+    end: Annotated[Optional[str], typer.Option("--end", help="End time (ISO 8601)")] = None,
+):
+    """Recent trade executions from the API."""
+    opts = ctx.obj
+    info = get_info(opts["testnet"])
+    addr = get_address()
+
+    resolved = None
+    if asset:
+        resolver = get_resolver(info)
+        resolved = resolver.resolve(asset)
+
+    if start or end:
+        start_ms = parse_time(start) if start else 0
+        end_ms = parse_time(end) if end else None
+        data = info.user_fills_by_time(addr, start_ms, end_ms)
+    else:
+        data = info.user_fills(addr)
+
+    result = []
+    for f in data:
+        coin = f["coin"]
+        if resolved and coin != resolved:
+            continue
+        result.append({
+            "asset": coin,
+            "side": "buy" if f["side"] == "B" else "sell",
+            "direction": f.get("dir", ""),
+            "price": f["px"],
+            "size": f["sz"],
+            "fee": f.get("fee", ""),
+            "closed_pnl": f.get("closedPnl", "0"),
+            "time": format_timestamp(f.get("time", 0)),
+        })
+
+    result = result[-limit:]
+    output(result, opts["fields"])
+
+
+@app.command()
+def trades(
+    ctx: typer.Context,
+    asset_name: Annotated[Optional[str], typer.Option("--asset", help="Filter by asset")] = None,
+    limit: Annotated[int, typer.Option("--limit", help="Number of trades")] = 20,
+):
+    """Local trade log (from data/trades.jsonl)."""
+    opts = ctx.obj
+    trades_file = Path("data/trades.jsonl")
+
+    if not trades_file.exists():
+        output([], opts["fields"])
+        return
+
+    result = []
+    for line in trades_file.read_text().strip().split("\n"):
+        if not line:
+            continue
+        trade = json.loads(line)
+        if asset_name and trade.get("asset") != asset_name:
+            continue
+        result.append(trade)
+
+    result = result[-limit:]
+    output(result, opts["fields"])

hl_cli/main.py

@@ -0,0 +1,30 @@
+"""hl — Agent-first CLI for Hyperliquid trading."""
+
+from typing import Optional
+
+import typer
+
+app = typer.Typer(
+    name="hl",
+    add_completion=False,
+    no_args_is_help=True,
+    help="Agent-first CLI for Hyperliquid perp trading.",
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    fields: Optional[str] = typer.Option(None, "--fields", help="Comma-separated field projection"),
+    verbose: bool = typer.Option(False, "--verbose", help="Debug info to stderr"),
+    testnet: bool = typer.Option(False, "--testnet", help="Use testnet endpoints"),
+):
+    """Hyperliquid perp trading CLI. JSON output by default."""
+    ctx.ensure_object(dict)
+    ctx.obj["fields"] = fields
+    ctx.obj["verbose"] = verbose
+    ctx.obj["testnet"] = testnet
+
+
+# Register all commands — must be after app is defined
+from hl_cli.commands import orient, research, act, review  # noqa: E402, F401

hl_cli/output.py

@@ -0,0 +1,84 @@
+"""Output formatting, errors, and time utilities."""
+
+import json
+import sys
+from datetime import datetime, timezone
+
+
+def output(data, fields=None):
+    """Write data to stdout as compact JSON."""
+    if fields:
+        data = _project(data, fields)
+    sys.stdout.write(json.dumps(data, separators=(",", ":")) + "\n")
+
+
+def die(error_code: str, message: str, hint: str = None, exit_code: int = 1):
+    """Write structured error to stdout and exit."""
+    err = {"error": error_code, "message": message}
+    if hint:
+        err["hint"] = hint
+    sys.stdout.write(json.dumps(err, separators=(",", ":")) + "\n")
+    raise SystemExit(exit_code)
+
+
+def debug(message: str, verbose: bool = False):
+    """Write debug info to stderr."""
+    if verbose:
+        sys.stderr.write(f"[debug] {message}\n")
+
+
+def _project(data, fields_str: str):
+    """Filter data to only include specified fields."""
+    fields = {f.strip() for f in fields_str.split(",")}
+    if isinstance(data, list):
+        return [
+            {k: v for k, v in item.items() if k in fields}
+            for item in data
+            if isinstance(item, dict)
+        ]
+    elif isinstance(data, dict):
+        return {k: v for k, v in data.items() if k in fields}
+    return data
+
+
+def parse_time(s: str) -> int:
+    """Parse time string to unix milliseconds."""
+    dt = datetime.fromisoformat(s)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return int(dt.timestamp() * 1000)
+
+
+def format_timestamp(ms) -> str:
+    """Format unix milliseconds to ISO 8601."""
+    if isinstance(ms, (int, float)) and ms > 0:
+        dt = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
+        return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+    return str(ms)
+
+
+INTERVAL_MS = {
+    "1m": 60_000,
+    "3m": 180_000,
+    "5m": 300_000,
+    "15m": 900_000,
+    "30m": 1_800_000,
+    "1h": 3_600_000,
+    "2h": 7_200_000,
+    "4h": 14_400_000,
+    "8h": 28_800_000,
+    "12h": 43_200_000,
+    "1d": 86_400_000,
+    "3d": 259_200_000,
+    "1w": 604_800_000,
+    "1M": 2_592_000_000,
+}
+
+
+def interval_to_ms(interval: str) -> int:
+    """Convert candle interval string to milliseconds."""
+    ms = INTERVAL_MS.get(interval)
+    if ms is None:
+        valid = ", ".join(INTERVAL_MS.keys())
+        die("input_error", f"Invalid interval: {interval}", hint=f"Valid intervals: {valid}")
+    return ms

hl_cli/resolver.py

@@ -0,0 +1,151 @@
+"""Asset name resolution — maps short tickers to full coin names."""
+
+from hyperliquid.info import Info
+
+from hl_cli.output import die
+
+
+class Resolver:
+    """Resolves user-typed asset names to SDK coin names.
+
+    - Exact match on known coin (e.g. "BTC", "xyz:TSLA") -> use it
+    - Case-insensitive match on default perps -> use it
+    - Short HIP-3 ticker (e.g. "TSLA") -> resolve, error if ambiguous
+    - Lazy-loads HIP-3 dex metadata on first miss against default perps
+    """
+
+    def __init__(self, info: Info):
+        self.info = info
+        self._dexes_loaded = False
+        self._short_map: dict[str, list[str]] = {}  # UPPER ticker -> [full names]
+        self._build_default_map()
+
+    def _build_default_map(self):
+        """Index default perps by uppercase name."""
+        for name in self.info.coin_to_asset:
+            if ":" not in name and "@" not in name:
+                key = name.upper()
+                self._short_map.setdefault(key, []).append(name)
+
+    def _load_dexes(self):
+        """Lazily load all HIP-3 deployer metadata into the Info client."""
+        if self._dexes_loaded:
+            return
+        self._dexes_loaded = True
+
+        try:
+            dex_list = self.info.post("/info", {"type": "perpDexs"})
+        except Exception:
+            return  # can't load dexes, resolve will fail with unknown_asset
+
+        for idx, dex_info in enumerate(dex_list[1:]):  # skip default dex
+            dex_name = dex_info["name"]
+            try:
+                dex_meta = self.info.meta(dex=dex_name)
+                offset = 110000 + idx * 10000
+                self.info.set_perp_meta(dex_meta, offset)
+
+                # Index by short ticker for disambiguation
+                for asset_info in dex_meta["universe"]:
+                    full_name = asset_info["name"]
+                    # The API may or may not prefix with dex name
+                    if ":" in full_name:
+                        _, ticker = full_name.split(":", 1)
+                    else:
+                        ticker = full_name
+                    key = ticker.upper()
+                    self._short_map.setdefault(key, []).append(full_name)
+            except Exception:
+                continue
+
+    def _find_exact(self, name: str) -> str | None:
+        """Case-insensitive exact match against all known coins."""
+        if name in self.info.coin_to_asset:
+            return name
+        upper = name.upper()
+        for known in self.info.coin_to_asset:
+            if known.upper() == upper:
+                return known
+        return None
+
+    def resolve(self, name: str) -> str:
+        """Resolve a user-typed asset name to the SDK coin name.
+
+        Returns the canonical coin name or calls die() on error.
+        """
+        # Exact match (already known to SDK)
+        exact = self._find_exact(name)
+        if exact:
+            return exact
+
+        # Short-name match against indexed tickers
+        key = name.upper()
+        matches = self._short_map.get(key)
+
+        if matches is None and not self._dexes_loaded:
+            # Try loading HIP-3 dexes
+            self._load_dexes()
+            # Re-check exact match (full names now loaded)
+            exact = self._find_exact(name)
+            if exact:
+                return exact
+            matches = self._short_map.get(key)
+
+        if not matches:
+            die(
+                "unknown_asset",
+                f"Unknown asset: {name}",
+                hint="Use 'hl assets' to list available assets, or specify full name like 'xyz:TSLA'",
+                exit_code=4,
+            )
+
+        if len(matches) == 1:
+            return matches[0]
+
+        # Multiple matches — prefer default perp (no colon) over HIP-3
+        defaults = [m for m in matches if ":" not in m]
+        if len(defaults) == 1:
+            return defaults[0]
+
+        # Ambiguous — build match info for the error
+        mids = {}
+        try:
+            mids = self.info.all_mids()
+            # Also fetch HIP-3 mids for the deployers involved
+            dex_list = self.info.post("/info", {"type": "perpDexs"})
+            deployers = {m.split(":")[0] for m in matches if ":" in m}
+            for dex_info in dex_list[1:]:
+                if dex_info["name"] in deployers:
+                    dex_mids = self.info.post("/info", {"type": "allMids", "dex": dex_info["name"]})
+                    mids.update(dex_mids)
+        except Exception:
+            pass
+
+        match_info = []
+        for m in matches:
+            deployer = m.split(":")[0] if ":" in m else ""
+            match_info.append({"asset": m, "deployer": deployer, "mid": mids.get(m, "")})
+
+        import json
+        import sys
+
+        err = {
+            "error": "ambiguous_asset",
+            "message": f"{name} matches multiple markets",
+            "matches": match_info,
+            "hint": f"Use full name: hl <command> {matches[0]} ...",
+        }
+        sys.stdout.write(json.dumps(err, separators=(",", ":")) + "\n")
+        raise SystemExit(4)
+
+
+# Module-level singleton per Info instance
+_resolvers: dict[int, Resolver] = {}
+
+
+def get_resolver(info: Info) -> Resolver:
+    """Get or create a Resolver for the given Info client."""
+    key = id(info)
+    if key not in _resolvers:
+        _resolvers[key] = Resolver(info)
+    return _resolvers[key]

hyperliquid_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+hl_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hl_cli/client.py,sha256=pCQ2flLJjsQBNt_X0OFDcNH-UQgXtL4RtEcwazMsAis,1975
+hl_cli/main.py,sha256=R7kyEN-Upw0HDiA6yN-hXo2MfNd0H7ts2rW_sB-MK8Q,893
+hl_cli/output.py,sha256=IDjZfAN-rlZFhpV_0RyAWQVFZc5xh4f-8wtiIy63qXo,2364
+hl_cli/resolver.py,sha256=NrtOqd0KTF0HpfWcOV5bgbbqMSrpNQuEDAhMRo-My84,5335
+hl_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hl_cli/commands/act.py,sha256=d3mCYquw4Aawco6p9MaZi114J-NshsffYCjy74VRoTA,9901
+hl_cli/commands/orient.py,sha256=cgx9ifxtAuaZWm-0jXJREF9CzhJ0MGvKWp67hoIh1tM,5442
+hl_cli/commands/research.py,sha256=AZt6VNlcIyfAH9jBjGPL_RdOiwYyMeNcjpNdw9IfwBY,10382
+hl_cli/commands/review.py,sha256=WHCTjbHzPmzuizYj82wQjfNdPK6WMuJo6-JaNT4gB6g,2535
+hyperliquid_cli-0.1.0.dist-info/METADATA,sha256=JUWCtZaG2iJkRSJryPHVrNmPqSCuzqFHBKak0f0GsHs,2142
+hyperliquid_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hyperliquid_cli-0.1.0.dist-info/entry_points.txt,sha256=bhcbj-NYrC5Ehnxljd9-y51hFwLdBM14jyMofWxa0pQ,39
+hyperliquid_cli-0.1.0.dist-info/licenses/LICENSE,sha256=cGXuzMAOqozvfDc6j_SY0yqCr5jABYqf1m0De5VQN_k,1062
+hyperliquid_cli-0.1.0.dist-info/RECORD,,

hyperliquid_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hyperliquid_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hl = hl_cli.main:app

hyperliquid_cli-0.1.0.dist-info/licenses/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.