| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659 |
- #!/usr/bin/env python3
- """
- Hyperliquid CLI Tool for Hermes Agent
- -------------------------------------
- Queries the Hyperliquid info endpoint for market and account data.
- Uses only Python standard library - no external packages required.
- Usage:
- python3 hyperliquid_client.py dexs
- python3 hyperliquid_client.py markets [--dex DEX] [--limit N]
- python3 hyperliquid_client.py spots [--limit N]
- python3 hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24]
- python3 hyperliquid_client.py funding <coin> [--hours 72]
- python3 hyperliquid_client.py l2 <coin> [--levels 10]
- python3 hyperliquid_client.py state [address] [--dex DEX]
- python3 hyperliquid_client.py spot-balances [address]
- python3 hyperliquid_client.py fills [address] [--hours N] [--limit N]
- python3 hyperliquid_client.py orders [address] [--limit N]
- python3 hyperliquid_client.py review [address] [--coin COIN] [--hours N]
- python3 hyperliquid_client.py export <coin> [--interval 1h] [--hours N]
- Environment:
- HYPERLIQUID_API_URL Override API base URL
- (default: https://api.hyperliquid.xyz)
- HYPERLIQUID_USER_ADDRESS Default address for state/fills/orders/review commands
- """
- from __future__ import annotations
- import argparse
- import datetime as dt
- import json
- import os
- import sys
- import time
- import urllib.error
- import urllib.request
- from collections import Counter
- from pathlib import Path
- from typing import Any, Dict, Iterable, List, Optional
- USER_AGENT = "HermesAgent/1.0"
- DEFAULT_USER_ENV = "HYPERLIQUID_USER_ADDRESS"
- DEFAULT_API_BASE = "https://api.hyperliquid.xyz"
- def _hermes_home() -> Path:
- return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser()
- def _dotenv_paths() -> list[Path]:
- paths: list[Path] = []
- project_env = Path.cwd() / ".env"
- if project_env.exists():
- paths.append(project_env)
- user_env = _hermes_home() / ".env"
- if user_env.exists():
- paths.append(user_env)
- return paths
- def _load_dotenv_values() -> dict[str, str]:
- values: dict[str, str] = {}
- for env_path in _dotenv_paths():
- try:
- lines = env_path.read_text(encoding="utf-8").splitlines()
- except UnicodeDecodeError:
- lines = env_path.read_text(encoding="latin-1").splitlines()
- for raw_line in lines:
- line = raw_line.strip()
- if not line or line.startswith("#") or "=" not in line:
- continue
- key, _, value = raw_line.partition("=")
- key = key.strip()
- value = value.strip()
- if value.startswith('"') and value.endswith('"') and len(value) >= 2:
- value = value[1:-1].replace('\\"', '"').replace('\\\\', '\\')
- values[key] = value
- return values
- def _env_lookup(key: str, default: str = "") -> str:
- value = os.environ.get(key, "").strip()
- if value:
- return value
- dotenv_value = _load_dotenv_values().get(key, "").strip()
- if dotenv_value:
- return dotenv_value
- return default
- def _api_base() -> str:
- return _env_lookup("HYPERLIQUID_API_URL", DEFAULT_API_BASE).rstrip("/")
- def _info_url() -> str:
- api_base = _api_base()
- if api_base.endswith("/info"):
- return api_base
- return f"{api_base}/info"
- def _resolve_user(user: Optional[str]) -> str:
- candidate = (user or "").strip()
- if candidate:
- return candidate
- env_value = _env_lookup(DEFAULT_USER_ENV, "")
- if env_value:
- return env_value
- sys.exit(
- "Missing Hyperliquid address. Pass <address> explicitly or set "
- f"{DEFAULT_USER_ENV} in your environment or {_hermes_home() / '.env'}."
- )
- def _post_info(payload: dict[str, Any], timeout: int = 20, retries: int = 2) -> Any:
- data = json.dumps(payload).encode("utf-8")
- headers = {
- "Content-Type": "application/json",
- "Accept": "application/json",
- "User-Agent": USER_AGENT,
- }
- for attempt in range(retries + 1):
- request = urllib.request.Request(_info_url(), data=data, headers=headers, method="POST")
- try:
- with urllib.request.urlopen(request, timeout=timeout) as response:
- body = json.load(response)
- return body
- except urllib.error.HTTPError as exc:
- if exc.code == 429 and attempt < retries:
- time.sleep(1.5 * (attempt + 1))
- continue
- sys.exit(f"Hyperliquid HTTP error: {exc}")
- except urllib.error.URLError as exc:
- sys.exit(f"Hyperliquid connection error: {exc}")
- except json.JSONDecodeError as exc:
- sys.exit(f"Hyperliquid response was not valid JSON: {exc}")
- return None
- def _safe_float(value: Any) -> Optional[float]:
- try:
- if value is None or value == "":
- return None
- return float(value)
- except (TypeError, ValueError):
- return None
- def _limit_items(items: list[dict[str, Any]], limit: int) -> list[dict[str, Any]]:
- if limit <= 0:
- return items
- return items[:limit]
- def _hours_ago_ms(hours: float, now_ms: Optional[int] = None) -> int:
- end_ms = now_ms if now_ms is not None else int(time.time() * 1000)
- return end_ms - int(hours * 60 * 60 * 1000)
- def _format_timestamp_ms(value: Any) -> str:
- try:
- ts_ms = int(value)
- except (TypeError, ValueError):
- return "-"
- return dt.datetime.fromtimestamp(ts_ms / 1000, dt.UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
- def _compact_number(value: Any, decimals: int = 2) -> str:
- number = _safe_float(value)
- if number is None:
- return "-"
- sign = "-" if number < 0 else ""
- number = abs(number)
- if number >= 1_000_000_000:
- return f"{sign}{number / 1_000_000_000:.{decimals}f}B"
- if number >= 1_000_000:
- return f"{sign}{number / 1_000_000:.{decimals}f}M"
- if number >= 1_000:
- return f"{sign}{number / 1_000:.{decimals}f}K"
- if number >= 100:
- return f"{sign}{number:.2f}"
- if number >= 1:
- return f"{sign}{number:.4f}".rstrip("0").rstrip(".")
- return f"{sign}{number:.6f}".rstrip("0").rstrip(".")
- def _format_price(value: Any) -> str:
- number = _safe_float(value)
- if number is None:
- return "-"
- if abs(number) >= 1000:
- return f"{number:,.2f}"
- if abs(number) >= 1:
- return f"{number:,.4f}".rstrip("0").rstrip(".")
- return f"{number:,.6f}".rstrip("0").rstrip(".")
- def _format_percent(value: Any, decimals: int = 2) -> str:
- number = _safe_float(value)
- if number is None:
- return "-"
- return f"{number:+.{decimals}f}%"
- def _format_fraction_percent(value: Any, decimals: int = 4) -> str:
- number = _safe_float(value)
- if number is None:
- return "-"
- return f"{number * 100:+.{decimals}f}%"
- def _percent_change(current: Any, previous: Any) -> Optional[float]:
- curr = _safe_float(current)
- prev = _safe_float(previous)
- if curr is None or prev is None or prev == 0:
- return None
- return ((curr - prev) / prev) * 100
- def _short_address(address: Any) -> str:
- if not isinstance(address, str) or len(address) < 12:
- return str(address)
- return f"{address[:6]}...{address[-4:]}"
- def _render_table(headers: list[tuple[str, str]], rows: list[dict[str, Any]]) -> str:
- if not rows:
- return "(no data)"
- prepared_rows: list[list[str]] = []
- widths = [len(label) for label, _ in headers]
- for row in rows:
- rendered = []
- for index, (_label, key) in enumerate(headers):
- value = row.get(key, "")
- text = str(value)
- rendered.append(text)
- widths[index] = max(widths[index], len(text))
- prepared_rows.append(rendered)
- lines = []
- header_line = " ".join(label.ljust(widths[idx]) for idx, (label, _key) in enumerate(headers))
- separator = " ".join("-" * widths[idx] for idx in range(len(headers)))
- lines.extend([header_line, separator])
- for rendered in prepared_rows:
- lines.append(" ".join(rendered[idx].ljust(widths[idx]) for idx in range(len(rendered))))
- return "\n".join(lines)
- def _normalize_dexs(payload: Any) -> list[dict[str, Any]]:
- rows: list[dict[str, Any]] = []
- if not isinstance(payload, list):
- return rows
- for index, item in enumerate(payload):
- if item is None:
- rows.append(
- {
- "index": index,
- "name": "",
- "label": "first-perp-dex",
- "full_name": "First perp dex",
- "deployer": "-",
- "asset_caps": 0,
- }
- )
- continue
- if not isinstance(item, dict):
- continue
- caps = item.get("assetToStreamingOiCap") or []
- rows.append(
- {
- "index": index,
- "name": item.get("name", ""),
- "label": item.get("name") or "first-perp-dex",
- "full_name": item.get("fullName") or "-",
- "deployer": item.get("deployer") or "-",
- "asset_caps": len(caps) if isinstance(caps, list) else 0,
- }
- )
- return rows
- def _normalize_perp_markets(payload: Any) -> list[dict[str, Any]]:
- if not isinstance(payload, list) or len(payload) < 2:
- return []
- meta = payload[0] if isinstance(payload[0], dict) else {}
- ctxs = payload[1] if isinstance(payload[1], list) else []
- universe = meta.get("universe") if isinstance(meta, dict) else []
- if not isinstance(universe, list):
- return []
- rows: list[dict[str, Any]] = []
- for index, spec in enumerate(universe):
- if not isinstance(spec, dict):
- continue
- ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {}
- mark_px = ctx.get("markPx") or ctx.get("midPx") or ctx.get("oraclePx")
- row = {
- "coin": spec.get("name", f"asset-{index}"),
- "mark_px": mark_px,
- "mid_px": ctx.get("midPx"),
- "oracle_px": ctx.get("oraclePx"),
- "prev_day_px": ctx.get("prevDayPx"),
- "change_pct": _percent_change(mark_px, ctx.get("prevDayPx")),
- "funding": ctx.get("funding"),
- "premium": ctx.get("premium"),
- "open_interest": ctx.get("openInterest"),
- "day_ntl_vlm": ctx.get("dayNtlVlm"),
- "day_base_vlm": ctx.get("dayBaseVlm"),
- "max_leverage": spec.get("maxLeverage"),
- "sz_decimals": spec.get("szDecimals"),
- "is_delisted": bool(spec.get("isDelisted")),
- "only_isolated": bool(spec.get("onlyIsolated")),
- "margin_mode": spec.get("marginMode") or "-",
- }
- rows.append(row)
- return rows
- def _normalize_spot_markets(payload: Any) -> list[dict[str, Any]]:
- if not isinstance(payload, list) or len(payload) < 2:
- return []
- meta = payload[0] if isinstance(payload[0], dict) else {}
- ctxs = payload[1] if isinstance(payload[1], list) else []
- pairs = meta.get("universe") if isinstance(meta, dict) else []
- tokens = meta.get("tokens") if isinstance(meta, dict) else []
- token_lookup = {}
- if isinstance(tokens, list):
- for token in tokens:
- if isinstance(token, dict) and "index" in token:
- token_lookup[token["index"]] = token.get("name", str(token["index"]))
- rows: list[dict[str, Any]] = []
- if not isinstance(pairs, list):
- return rows
- for index, pair in enumerate(pairs):
- if not isinstance(pair, dict):
- continue
- ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {}
- raw_name = pair.get("name", f"@{index}")
- tokens_for_pair = pair.get("tokens") if isinstance(pair.get("tokens"), list) else []
- display_name = raw_name
- if "/" not in raw_name and len(tokens_for_pair) == 2:
- base = token_lookup.get(tokens_for_pair[0], str(tokens_for_pair[0]))
- quote = token_lookup.get(tokens_for_pair[1], str(tokens_for_pair[1]))
- display_name = f"{base}/{quote} ({raw_name})"
- mark_px = ctx.get("markPx") or ctx.get("midPx")
- rows.append(
- {
- "pair": raw_name,
- "display_name": display_name,
- "mark_px": mark_px,
- "mid_px": ctx.get("midPx"),
- "prev_day_px": ctx.get("prevDayPx"),
- "change_pct": _percent_change(mark_px, ctx.get("prevDayPx")),
- "day_ntl_vlm": ctx.get("dayNtlVlm"),
- }
- )
- return rows
- def _normalize_candles(payload: Any) -> list[dict[str, Any]]:
- rows: list[dict[str, Any]] = []
- if not isinstance(payload, list):
- return rows
- for candle in payload:
- if not isinstance(candle, dict):
- continue
- rows.append(
- {
- "time": candle.get("t") or candle.get("time"),
- "open": candle.get("o"),
- "high": candle.get("h"),
- "low": candle.get("l"),
- "close": candle.get("c"),
- "volume": candle.get("v"),
- "trades": candle.get("n"),
- }
- )
- rows.sort(key=lambda item: int(item.get("time") or 0))
- return rows
- def _normalize_funding_history(payload: Any) -> list[dict[str, Any]]:
- rows: list[dict[str, Any]] = []
- if not isinstance(payload, list):
- return rows
- for item in payload:
- if not isinstance(item, dict):
- continue
- rows.append(
- {
- "coin": item.get("coin", "-"),
- "funding_rate": item.get("fundingRate"),
- "premium": item.get("premium"),
- "time": item.get("time"),
- }
- )
- rows.sort(key=lambda item: int(item.get("time") or 0))
- return rows
- def _normalize_book_levels(payload: Any) -> dict[str, list[dict[str, Any]]]:
- if not isinstance(payload, dict):
- return {"bids": [], "asks": []}
- levels = payload.get("levels")
- if not isinstance(levels, list) or len(levels) < 2:
- return {"bids": [], "asks": []}
- def convert(side: Iterable[Any]) -> list[dict[str, Any]]:
- converted = []
- for entry in side:
- if isinstance(entry, dict):
- converted.append(
- {
- "px": entry.get("px"),
- "sz": entry.get("sz"),
- "orders": entry.get("n"),
- }
- )
- elif isinstance(entry, (list, tuple)) and len(entry) >= 2:
- converted.append(
- {
- "px": entry[0],
- "sz": entry[1],
- "orders": entry[2] if len(entry) > 2 else None,
- }
- )
- return converted
- return {"bids": convert(levels[0]), "asks": convert(levels[1])}
- def _normalize_positions(payload: Any) -> dict[str, Any]:
- if not isinstance(payload, dict):
- return {"summary": {}, "positions": []}
- positions: list[dict[str, Any]] = []
- for item in payload.get("assetPositions", []):
- if not isinstance(item, dict):
- continue
- position = item.get("position") if isinstance(item.get("position"), dict) else item
- if not isinstance(position, dict):
- continue
- leverage = position.get("leverage") if isinstance(position.get("leverage"), dict) else {}
- positions.append(
- {
- "coin": position.get("coin", "-"),
- "size": position.get("szi"),
- "entry_px": position.get("entryPx"),
- "position_value": position.get("positionValue"),
- "unrealized_pnl": position.get("unrealizedPnl"),
- "return_on_equity": position.get("returnOnEquity"),
- "liquidation_px": position.get("liquidationPx"),
- "margin_used": position.get("marginUsed"),
- "leverage": leverage.get("value"),
- "leverage_type": leverage.get("type"),
- }
- )
- positions.sort(
- key=lambda item: abs(_safe_float(item.get("position_value")) or 0.0),
- reverse=True,
- )
- summary = payload.get("marginSummary") if isinstance(payload.get("marginSummary"), dict) else {}
- cross_summary = (
- payload.get("crossMarginSummary") if isinstance(payload.get("crossMarginSummary"), dict) else {}
- )
- return {
- "summary": {
- "account_value": summary.get("accountValue"),
- "total_ntl_pos": summary.get("totalNtlPos"),
- "total_raw_usd": summary.get("totalRawUsd"),
- "withdrawable": payload.get("withdrawable"),
- "cross_account_value": cross_summary.get("accountValue"),
- },
- "positions": positions,
- }
- def _normalize_spot_balances(payload: Any) -> list[dict[str, Any]]:
- if not isinstance(payload, dict):
- return []
- rows: list[dict[str, Any]] = []
- for item in payload.get("balances", []):
- if not isinstance(item, dict):
- continue
- rows.append(
- {
- "coin": item.get("coin", item.get("token", "-")),
- "total": item.get("total"),
- "hold": item.get("hold"),
- "entry_ntl": item.get("entryNtl"),
- }
- )
- rows.sort(key=lambda item: abs(_safe_float(item.get("entry_ntl")) or 0.0), reverse=True)
- return rows
- def _normalize_fills(payload: Any) -> list[dict[str, Any]]:
- rows: list[dict[str, Any]] = []
- if not isinstance(payload, list):
- return rows
- for item in payload:
- if not isinstance(item, dict):
- continue
- fill = item.get("fill") if isinstance(item.get("fill"), dict) else item
- rows.append(
- {
- "coin": fill.get("coin", "-"),
- "dir": fill.get("dir") or fill.get("side") or "-",
- "px": fill.get("px"),
- "sz": fill.get("sz"),
- "closed_pnl": fill.get("closedPnl"),
- "fee": fill.get("fee"),
- "fee_token": fill.get("feeToken"),
- "start_position": fill.get("startPosition"),
- "time": fill.get("time"),
- "hash": fill.get("hash"),
- "oid": fill.get("oid"),
- "twap_id": item.get("twapId"),
- }
- )
- rows.sort(key=lambda item: int(item.get("time") or 0), reverse=True)
- return rows
- def _normalize_orders(payload: Any) -> list[dict[str, Any]]:
- rows: list[dict[str, Any]] = []
- if not isinstance(payload, list):
- return rows
- for item in payload:
- if not isinstance(item, dict):
- continue
- order = item.get("order") if isinstance(item.get("order"), dict) else item
- rows.append(
- {
- "coin": order.get("coin", "-"),
- "side": order.get("side", "-"),
- "limit_px": order.get("limitPx") or order.get("px"),
- "size": order.get("sz") or order.get("origSz"),
- "timestamp": item.get("statusTimestamp")
- or order.get("timestamp")
- or order.get("time"),
- "status": item.get("status") or order.get("status") or "-",
- "oid": order.get("oid"),
- "order_type": order.get("orderType") or "-",
- }
- )
- rows.sort(key=lambda item: int(item.get("timestamp") or 0), reverse=True)
- return rows
- def _direction_bucket(direction: Any) -> str:
- text = str(direction or "").strip().lower()
- if "open" in text and "long" in text:
- return "open_long"
- if "close" in text and "long" in text:
- return "close_long"
- if "open" in text and "short" in text:
- return "open_short"
- if "close" in text and "short" in text:
- return "close_short"
- if text in {"b", "buy"}:
- return "buy"
- if text in {"s", "sell"}:
- return "sell"
- return "other"
- def _average(values: Iterable[Optional[float]]) -> Optional[float]:
- clean_values = [value for value in values if value is not None]
- if not clean_values:
- return None
- return round(sum(clean_values) / len(clean_values), 12)
- def _is_spot_coin(coin: str) -> bool:
- return "/" in coin or coin.startswith("@")
- def _safe_info_query(payload: dict[str, Any]) -> Any:
- try:
- return _post_info(payload)
- except SystemExit:
- return None
- def _market_context_for_coin(coin: str, interval: str, start_ms: int, end_ms: int) -> dict[str, Any]:
- candles = _normalize_candles(
- _safe_info_query(
- {
- "type": "candleSnapshot",
- "req": {
- "coin": coin,
- "interval": interval,
- "startTime": start_ms,
- "endTime": end_ms,
- },
- }
- )
- )
- funding_history: list[dict[str, Any]] = []
- if not _is_spot_coin(coin):
- funding_history = _normalize_funding_history(
- _safe_info_query(
- {
- "type": "fundingHistory",
- "coin": coin,
- "startTime": start_ms,
- "endTime": end_ms,
- }
- )
- )
- candle_change = None
- if candles:
- candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open"))
- funding_average = _average(_safe_float(item.get("funding_rate")) for item in funding_history)
- return {
- "coin": coin,
- "interval": interval,
- "candle_count": len(candles),
- "price_change_pct": candle_change,
- "window_open": candles[0].get("open") if candles else None,
- "window_close": candles[-1].get("close") if candles else None,
- "average_funding_rate": funding_average,
- "funding_samples": len(funding_history),
- }
- def _build_coin_review(coin: str, fills: list[dict[str, Any]], interval: str, start_ms: int, end_ms: int) -> dict[str, Any]:
- pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills]
- fee_values = [_safe_float(fill.get("fee")) for fill in fills]
- scored = [value for value in pnl_values if value is not None]
- wins = [value for value in scored if value > 0]
- losses = [value for value in scored if value < 0]
- breakeven = [value for value in scored if value == 0]
- direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills)
- market_context = _market_context_for_coin(coin, interval, start_ms, end_ms)
- total_pnl = sum(value for value in pnl_values if value is not None)
- total_fees = sum(value for value in fee_values if value is not None)
- net_after_fees = total_pnl - total_fees
- if direction_counts["open_long"] > direction_counts["open_short"]:
- open_bias = "long"
- elif direction_counts["open_short"] > direction_counts["open_long"]:
- open_bias = "short"
- elif direction_counts["open_long"] or direction_counts["open_short"]:
- open_bias = "mixed"
- else:
- open_bias = "none"
- return {
- "coin": coin,
- "fill_count": len(fills),
- "realized_pnl": total_pnl,
- "total_fees": total_fees,
- "net_after_fees": net_after_fees,
- "wins": len(wins),
- "losses": len(losses),
- "breakeven": len(breakeven),
- "win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None,
- "open_long_count": direction_counts["open_long"],
- "open_short_count": direction_counts["open_short"],
- "close_long_count": direction_counts["close_long"],
- "close_short_count": direction_counts["close_short"],
- "open_bias": open_bias,
- "market_context": market_context,
- }
- def _review_findings(summary: dict[str, Any], coin_reviews: list[dict[str, Any]]) -> list[str]:
- findings: list[str] = []
- if summary["fill_count"] == 0:
- return ["No fills were found in the requested review window."]
- if summary["outcome_fill_count"] == 0:
- findings.append("Most fills in this window look like opens or adjustments, so realized-outcome review is limited until positions close.")
- if summary["net_after_fees"] < 0:
- findings.append(
- f"Net realized PnL after fees was negative ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)."
- )
- elif summary["net_after_fees"] > 0:
- findings.append(
- f"Net realized PnL after fees was positive ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)."
- )
- realized_abs = abs(summary["realized_pnl"])
- if summary["total_fees"] > 0:
- if realized_abs == 0:
- findings.append("Fees were non-trivial while realized PnL stayed flat, which usually means churn without enough edge.")
- elif summary["total_fees"] / realized_abs >= 0.25:
- ratio_pct = (summary["total_fees"] / realized_abs) * 100
- findings.append(f"Fees consumed about {ratio_pct:.1f}% of absolute realized PnL, so execution efficiency is materially affecting results.")
- if summary["fill_count"] >= 20 and summary["net_after_fees"] < 0:
- win_rate = summary.get("win_rate_pct")
- if win_rate is None or win_rate < 45:
- findings.append("Activity was high relative to results, which suggests overtrading in this review window.")
- if coin_reviews:
- worst_coin = min(coin_reviews, key=lambda item: item["net_after_fees"])
- best_coin = max(coin_reviews, key=lambda item: item["net_after_fees"])
- if worst_coin["net_after_fees"] < 0:
- findings.append(
- f"The weakest coin was {worst_coin['coin']} with net after fees of {_compact_number(worst_coin['net_after_fees'])}."
- )
- if best_coin["net_after_fees"] > 0 and best_coin["coin"] != worst_coin["coin"]:
- findings.append(
- f"The strongest coin was {best_coin['coin']} with net after fees of {_compact_number(best_coin['net_after_fees'])}."
- )
- for item in coin_reviews:
- market_change = item["market_context"].get("price_change_pct")
- if item["net_after_fees"] >= 0 or market_change is None:
- continue
- if market_change > 2 and item["open_short_count"] > item["open_long_count"]:
- findings.append(f"{item['coin']}: losses came while leaning short into a rising market window.")
- elif market_change < -2 and item["open_long_count"] > item["open_short_count"]:
- findings.append(f"{item['coin']}: losses came while leaning long into a falling market window.")
- deduped: list[str] = []
- for finding in findings:
- if finding not in deduped:
- deduped.append(finding)
- return deduped[:6]
- def _recent_fill_rows(fills: list[dict[str, Any]], limit: int) -> list[dict[str, Any]]:
- rows = []
- for fill in _limit_items(fills, limit):
- rows.append(
- {
- "time": fill.get("time"),
- "coin": fill.get("coin"),
- "dir": fill.get("dir"),
- "px": fill.get("px"),
- "sz": fill.get("sz"),
- "closed_pnl": fill.get("closed_pnl"),
- "fee": fill.get("fee"),
- "fee_token": fill.get("fee_token"),
- }
- )
- return rows
- def _coin_slug(coin: str) -> str:
- slug = str(coin or "market").strip().lower()
- for old, new in (("/", "-"), (":", "-"), ("@", "spot-"), (" ", "-")):
- slug = slug.replace(old, new)
- return slug or "market"
- def _default_export_path(coin: str, interval: str, hours: float) -> Path:
- hour_label = str(int(hours)) if float(hours).is_integer() else str(hours).replace(".", "p")
- filename = f"hyperliquid-{_coin_slug(coin)}-{interval}-{hour_label}h.json"
- return Path.cwd() / filename
- def _write_json_file(path: Path, payload: dict[str, Any]) -> None:
- path.parent.mkdir(parents=True, exist_ok=True)
- path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
- def _export_summary(candles: list[dict[str, Any]], funding_history: list[dict[str, Any]]) -> dict[str, Any]:
- candle_change = None
- if candles:
- candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open"))
- return {
- "candle_count": len(candles),
- "funding_count": len(funding_history),
- "window_open": candles[0].get("open") if candles else None,
- "window_close": candles[-1].get("close") if candles else None,
- "price_change_pct": candle_change,
- "average_funding_rate": _average(_safe_float(item.get("funding_rate")) for item in funding_history),
- }
- def run_dexs(_args: argparse.Namespace) -> dict[str, Any]:
- payload = _post_info({"type": "perpDexs"})
- rows = _normalize_dexs(payload)
- return {"api_url": _info_url(), "count": len(rows), "dexs": rows}
- def run_markets(args: argparse.Namespace) -> dict[str, Any]:
- payload: dict[str, Any] = {"type": "metaAndAssetCtxs"}
- if args.dex:
- payload["dex"] = args.dex
- rows = _normalize_perp_markets(_post_info(payload))
- if args.sort == "name":
- rows.sort(key=lambda item: item["coin"])
- elif args.sort == "oi":
- rows.sort(key=lambda item: _safe_float(item.get("open_interest")) or 0.0, reverse=True)
- elif args.sort == "funding_abs":
- rows.sort(key=lambda item: abs(_safe_float(item.get("funding")) or 0.0), reverse=True)
- elif args.sort == "change_abs":
- rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True)
- else:
- rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True)
- return {
- "dex": args.dex or "",
- "count": len(rows),
- "sort": args.sort,
- "markets": _limit_items(rows, args.limit),
- }
- def run_spots(args: argparse.Namespace) -> dict[str, Any]:
- rows = _normalize_spot_markets(_post_info({"type": "spotMetaAndAssetCtxs"}))
- if args.sort == "name":
- rows.sort(key=lambda item: item["display_name"])
- elif args.sort == "change_abs":
- rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True)
- else:
- rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True)
- return {"count": len(rows), "sort": args.sort, "pairs": _limit_items(rows, args.limit)}
- def run_candles(args: argparse.Namespace) -> dict[str, Any]:
- end_ms = int(time.time() * 1000)
- start_ms = _hours_ago_ms(args.hours, end_ms)
- payload = {
- "type": "candleSnapshot",
- "req": {
- "coin": args.coin,
- "interval": args.interval,
- "startTime": start_ms,
- "endTime": end_ms,
- },
- }
- candles = _normalize_candles(_post_info(payload))
- summary = {}
- if candles:
- highs = [_safe_float(item.get("high")) for item in candles]
- lows = [_safe_float(item.get("low")) for item in candles]
- clean_highs = [value for value in highs if value is not None]
- clean_lows = [value for value in lows if value is not None]
- summary = {
- "first_time": candles[0]["time"],
- "last_time": candles[-1]["time"],
- "open": candles[0]["open"],
- "close": candles[-1]["close"],
- "high": max(clean_highs) if clean_highs else None,
- "low": min(clean_lows) if clean_lows else None,
- "change_pct": _percent_change(candles[-1]["close"], candles[0]["open"]),
- }
- return {
- "coin": args.coin,
- "interval": args.interval,
- "hours": args.hours,
- "count": len(candles),
- "summary": summary,
- "candles": _limit_items(candles, args.limit),
- }
- def run_funding(args: argparse.Namespace) -> dict[str, Any]:
- end_ms = int(time.time() * 1000)
- start_ms = _hours_ago_ms(args.hours, end_ms)
- payload = {"type": "fundingHistory", "coin": args.coin, "startTime": start_ms, "endTime": end_ms}
- rows = _normalize_funding_history(_post_info(payload))
- avg_rate = None
- if rows:
- values = [_safe_float(item.get("funding_rate")) for item in rows]
- clean_values = [value for value in values if value is not None]
- if clean_values:
- avg_rate = sum(clean_values) / len(clean_values)
- return {
- "coin": args.coin,
- "hours": args.hours,
- "count": len(rows),
- "average_funding_rate": avg_rate,
- "history": _limit_items(list(reversed(rows)), args.limit),
- }
- def run_l2(args: argparse.Namespace) -> dict[str, Any]:
- payload: dict[str, Any] = {"type": "l2Book", "coin": args.coin}
- if args.n_sig_figs is not None:
- payload["nSigFigs"] = args.n_sig_figs
- if args.mantissa is not None:
- payload["mantissa"] = args.mantissa
- raw = _post_info(payload)
- levels = _normalize_book_levels(raw)
- return {
- "coin": args.coin,
- "time": raw.get("time") if isinstance(raw, dict) else None,
- "bids": _limit_items(levels["bids"], args.levels),
- "asks": _limit_items(levels["asks"], args.levels),
- }
- def run_state(args: argparse.Namespace) -> dict[str, Any]:
- user = _resolve_user(args.user)
- payload: dict[str, Any] = {"type": "clearinghouseState", "user": user}
- if args.dex:
- payload["dex"] = args.dex
- normalized = _normalize_positions(_post_info(payload))
- return {
- "user": user,
- "dex": args.dex or "",
- "summary": normalized["summary"],
- "positions": normalized["positions"],
- }
- def run_spot_balances(args: argparse.Namespace) -> dict[str, Any]:
- user = _resolve_user(args.user)
- payload = {"type": "spotClearinghouseState", "user": user}
- rows = _normalize_spot_balances(_post_info(payload))
- return {"user": user, "count": len(rows), "balances": _limit_items(rows, args.limit)}
- def run_fills(args: argparse.Namespace) -> dict[str, Any]:
- user = _resolve_user(args.user)
- payload: dict[str, Any] = {"user": user}
- if args.hours is not None:
- payload["type"] = "userFillsByTime"
- payload["startTime"] = _hours_ago_ms(args.hours)
- else:
- payload["type"] = "userFills"
- if args.aggregate_by_time:
- payload["aggregateByTime"] = True
- rows = _normalize_fills(_post_info(payload))
- return {
- "user": user,
- "hours": args.hours,
- "aggregate_by_time": args.aggregate_by_time,
- "count": len(rows),
- "fills": _limit_items(rows, args.limit),
- }
- def run_orders(args: argparse.Namespace) -> dict[str, Any]:
- user = _resolve_user(args.user)
- payload = {"type": "historicalOrders", "user": user}
- rows = _normalize_orders(_post_info(payload))
- return {"user": user, "count": len(rows), "orders": _limit_items(rows, args.limit)}
- def run_review(args: argparse.Namespace) -> dict[str, Any]:
- user = _resolve_user(args.user)
- end_ms = int(time.time() * 1000)
- start_ms = _hours_ago_ms(args.hours, end_ms)
- payload: dict[str, Any] = {"type": "userFillsByTime", "user": user, "startTime": start_ms}
- if args.aggregate_by_time:
- payload["aggregateByTime"] = True
- fills = _normalize_fills(_post_info(payload))
- if args.coin:
- target = args.coin.lower()
- fills = [fill for fill in fills if str(fill.get("coin", "")).lower() == target]
- fills = _limit_items(fills, args.fills)
- grouped: dict[str, list[dict[str, Any]]] = {}
- for fill in fills:
- grouped.setdefault(fill.get("coin", "-"), []).append(fill)
- coin_reviews = [
- _build_coin_review(coin, coin_fills, args.interval, start_ms, end_ms)
- for coin, coin_fills in sorted(grouped.items(), key=lambda item: len(item[1]), reverse=True)
- ]
- pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills]
- fee_values = [_safe_float(fill.get("fee")) for fill in fills]
- scored = [value for value in pnl_values if value is not None]
- wins = [value for value in scored if value > 0]
- losses = [value for value in scored if value < 0]
- direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills)
- total_pnl = sum(value for value in pnl_values if value is not None)
- total_fees = sum(value for value in fee_values if value is not None)
- summary = {
- "fill_count": len(fills),
- "scored_fill_count": len(scored),
- "outcome_fill_count": len(wins) + len(losses),
- "unique_coins": len(grouped),
- "realized_pnl": total_pnl,
- "total_fees": total_fees,
- "net_after_fees": total_pnl - total_fees,
- "wins": len(wins),
- "losses": len(losses),
- "breakeven": len([value for value in scored if value == 0]),
- "win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None,
- "open_long_count": direction_counts["open_long"],
- "open_short_count": direction_counts["open_short"],
- "close_long_count": direction_counts["close_long"],
- "close_short_count": direction_counts["close_short"],
- }
- return {
- "user": user,
- "coin_filter": args.coin,
- "hours": args.hours,
- "interval": args.interval,
- "fills_requested": args.fills,
- "summary": summary,
- "findings": _review_findings(summary, coin_reviews),
- "coin_reviews": coin_reviews,
- "recent_fills": _recent_fill_rows(fills, args.recent),
- }
- def run_export(args: argparse.Namespace) -> dict[str, Any]:
- end_ms = args.end_time_ms if args.end_time_ms is not None else int(time.time() * 1000)
- start_ms = _hours_ago_ms(args.hours, end_ms)
- candle_payload = {
- "type": "candleSnapshot",
- "req": {
- "coin": args.coin,
- "interval": args.interval,
- "startTime": start_ms,
- "endTime": end_ms,
- },
- }
- candles = _normalize_candles(_post_info(candle_payload))
- funding_history: list[dict[str, Any]] = []
- if not _is_spot_coin(args.coin):
- funding_history = _normalize_funding_history(
- _safe_info_query(
- {
- "type": "fundingHistory",
- "coin": args.coin,
- "startTime": start_ms,
- "endTime": end_ms,
- }
- )
- )
- output_path = Path(args.output) if args.output else _default_export_path(args.coin, args.interval, args.hours)
- payload = {
- "schema_version": "hyperliquid-market-export-v1",
- "source": {
- "api_url": _info_url(),
- "interval": args.interval,
- "coin": args.coin,
- "market_type": "spot" if _is_spot_coin(args.coin) else "perp",
- },
- "window": {
- "start_time_ms": start_ms,
- "end_time_ms": end_ms,
- "hours": args.hours,
- },
- "summary": _export_summary(candles, funding_history),
- "candles": candles,
- "funding_history": funding_history,
- }
- _write_json_file(output_path, payload)
- return {
- "coin": args.coin,
- "interval": args.interval,
- "hours": args.hours,
- "output_path": str(output_path),
- "summary": payload["summary"],
- "schema_version": payload["schema_version"],
- }
- def render_dexs(data: dict[str, Any]) -> str:
- rows = [
- {
- "label": item["label"],
- "full_name": item["full_name"],
- "deployer": _short_address(item["deployer"]),
- "asset_caps": item["asset_caps"],
- }
- for item in data["dexs"]
- ]
- return "\n".join(
- [
- f"API: {data['api_url']}",
- f"Perp dexs: {data['count']}",
- "",
- _render_table(
- [
- ("Dex", "label"),
- ("Full Name", "full_name"),
- ("Deployer", "deployer"),
- ("Asset Caps", "asset_caps"),
- ],
- rows,
- ),
- ]
- )
- def render_markets(data: dict[str, Any]) -> str:
- rows = [
- {
- "coin": item["coin"],
- "mark_px": _format_price(item["mark_px"]),
- "change_pct": _format_percent(item["change_pct"]),
- "funding": _format_fraction_percent(item["funding"]),
- "open_interest": _compact_number(item["open_interest"]),
- "day_ntl_vlm": _compact_number(item["day_ntl_vlm"]),
- }
- for item in data["markets"]
- ]
- lines = [
- f"Dex: {data['dex'] or 'first-perp-dex'}",
- f"Markets returned: {len(data['markets'])} of {data['count']}",
- "",
- _render_table(
- [
- ("Coin", "coin"),
- ("Mark", "mark_px"),
- ("Chg", "change_pct"),
- ("Funding", "funding"),
- ("OI", "open_interest"),
- ("24h Vol", "day_ntl_vlm"),
- ],
- rows,
- ),
- ]
- return "\n".join(lines)
- def render_spots(data: dict[str, Any]) -> str:
- rows = [
- {
- "pair": item["display_name"],
- "mark_px": _format_price(item["mark_px"]),
- "change_pct": _format_percent(item["change_pct"]),
- "day_ntl_vlm": _compact_number(item["day_ntl_vlm"]),
- }
- for item in data["pairs"]
- ]
- return "\n".join(
- [
- f"Spot pairs returned: {len(data['pairs'])} of {data['count']}",
- "",
- _render_table(
- [
- ("Pair", "pair"),
- ("Mark", "mark_px"),
- ("Chg", "change_pct"),
- ("24h Vol", "day_ntl_vlm"),
- ],
- rows,
- ),
- ]
- )
- def render_candles(data: dict[str, Any]) -> str:
- rows = [
- {
- "time": _format_timestamp_ms(item["time"]),
- "open": _format_price(item["open"]),
- "high": _format_price(item["high"]),
- "low": _format_price(item["low"]),
- "close": _format_price(item["close"]),
- "volume": _compact_number(item["volume"]),
- }
- for item in data["candles"]
- ]
- summary = data.get("summary") or {}
- lines = [
- f"Coin: {data['coin']}",
- f"Interval: {data['interval']}",
- f"Hours: {data['hours']}",
- f"Candles returned: {len(data['candles'])} of {data['count']}",
- ]
- if summary:
- lines.extend(
- [
- f"Open -> Close: {_format_price(summary.get('open'))} -> {_format_price(summary.get('close'))}",
- f"Range: {_format_price(summary.get('low'))} to {_format_price(summary.get('high'))}",
- f"Change: {_format_percent(summary.get('change_pct'))}",
- ]
- )
- lines.extend(
- [
- "",
- _render_table(
- [
- ("Time", "time"),
- ("Open", "open"),
- ("High", "high"),
- ("Low", "low"),
- ("Close", "close"),
- ("Volume", "volume"),
- ],
- rows,
- ),
- ]
- )
- return "\n".join(lines)
- def render_funding(data: dict[str, Any]) -> str:
- rows = [
- {
- "time": _format_timestamp_ms(item["time"]),
- "coin": item["coin"],
- "funding": _format_fraction_percent(item["funding_rate"]),
- "premium": _format_fraction_percent(item["premium"]),
- }
- for item in data["history"]
- ]
- lines = [
- f"Coin: {data['coin']}",
- f"Hours: {data['hours']}",
- f"Entries returned: {len(data['history'])} of {data['count']}",
- f"Average funding: {_format_fraction_percent(data['average_funding_rate'])}",
- "",
- _render_table(
- [
- ("Time", "time"),
- ("Coin", "coin"),
- ("Funding", "funding"),
- ("Premium", "premium"),
- ],
- rows,
- ),
- ]
- return "\n".join(lines)
- def render_l2(data: dict[str, Any]) -> str:
- bid_rows = [
- {"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"}
- for item in data["bids"]
- ]
- ask_rows = [
- {"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"}
- for item in data["asks"]
- ]
- lines = [
- f"Coin: {data['coin']}",
- f"Book time: {_format_timestamp_ms(data['time'])}",
- "",
- "Bids",
- _render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], bid_rows),
- "",
- "Asks",
- _render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], ask_rows),
- ]
- return "\n".join(lines)
- def render_state(data: dict[str, Any]) -> str:
- summary = data["summary"]
- position_rows = [
- {
- "coin": item["coin"],
- "size": item["size"],
- "entry_px": _format_price(item["entry_px"]),
- "position_value": _compact_number(item["position_value"]),
- "unrealized_pnl": _compact_number(item["unrealized_pnl"]),
- "roe": _format_fraction_percent(item["return_on_equity"], 2),
- "liq": _format_price(item["liquidation_px"]),
- "lev": f"{item['leverage'] or '-'}x",
- }
- for item in data["positions"]
- ]
- lines = [
- f"User: {data['user']}",
- f"Dex: {data['dex'] or 'first-perp-dex'}",
- f"Account value: {summary.get('account_value') or '-'}",
- f"Total notional position: {summary.get('total_ntl_pos') or '-'}",
- f"Withdrawable: {summary.get('withdrawable') or '-'}",
- f"Positions: {len(data['positions'])}",
- ]
- if position_rows:
- lines.extend(
- [
- "",
- _render_table(
- [
- ("Coin", "coin"),
- ("Size", "size"),
- ("Entry", "entry_px"),
- ("Pos Val", "position_value"),
- ("uPnL", "unrealized_pnl"),
- ("ROE", "roe"),
- ("Liq", "liq"),
- ("Lev", "lev"),
- ],
- position_rows,
- ),
- ]
- )
- return "\n".join(lines)
- def render_spot_balances(data: dict[str, Any]) -> str:
- rows = [
- {
- "coin": item["coin"],
- "total": _compact_number(item["total"]),
- "hold": _compact_number(item["hold"]),
- "entry_ntl": _compact_number(item["entry_ntl"]),
- }
- for item in data["balances"]
- ]
- return "\n".join(
- [
- f"User: {data['user']}",
- f"Balances returned: {len(data['balances'])} of {data['count']}",
- "",
- _render_table(
- [
- ("Coin", "coin"),
- ("Total", "total"),
- ("Hold", "hold"),
- ("Entry Ntl", "entry_ntl"),
- ],
- rows,
- ),
- ]
- )
- def render_fills(data: dict[str, Any]) -> str:
- rows = [
- {
- "time": _format_timestamp_ms(item["time"]),
- "coin": item["coin"],
- "dir": item["dir"],
- "px": _format_price(item["px"]),
- "sz": _compact_number(item["sz"]),
- "closed_pnl": _compact_number(item["closed_pnl"]),
- "fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(),
- }
- for item in data["fills"]
- ]
- lines = [
- f"User: {data['user']}",
- f"Aggregate by time: {data['aggregate_by_time']}",
- f"Fills returned: {len(data['fills'])} of {data['count']}",
- "",
- _render_table(
- [
- ("Time", "time"),
- ("Coin", "coin"),
- ("Dir", "dir"),
- ("Px", "px"),
- ("Sz", "sz"),
- ("Closed PnL", "closed_pnl"),
- ("Fee", "fee"),
- ],
- rows,
- ),
- ]
- return "\n".join(lines)
- def render_orders(data: dict[str, Any]) -> str:
- rows = [
- {
- "time": _format_timestamp_ms(item["timestamp"]),
- "coin": item["coin"],
- "side": item["side"],
- "limit_px": _format_price(item["limit_px"]),
- "size": _compact_number(item["size"]),
- "status": item["status"],
- "oid": item["oid"] or "-",
- }
- for item in data["orders"]
- ]
- return "\n".join(
- [
- f"User: {data['user']}",
- f"Orders returned: {len(data['orders'])} of {data['count']}",
- "",
- _render_table(
- [
- ("Time", "time"),
- ("Coin", "coin"),
- ("Side", "side"),
- ("Px", "limit_px"),
- ("Sz", "size"),
- ("Status", "status"),
- ("OID", "oid"),
- ],
- rows,
- ),
- ]
- )
- def render_review(data: dict[str, Any]) -> str:
- summary = data["summary"]
- coin_rows = [
- {
- "coin": item["coin"],
- "fills": item["fill_count"],
- "net": _compact_number(item["net_after_fees"]),
- "win_rate": _format_percent(item["win_rate_pct"]),
- "trend": _format_percent(item["market_context"].get("price_change_pct")),
- "funding": _format_fraction_percent(item["market_context"].get("average_funding_rate")),
- "bias": item["open_bias"],
- }
- for item in data["coin_reviews"]
- ]
- recent_rows = [
- {
- "time": _format_timestamp_ms(item["time"]),
- "coin": item["coin"],
- "dir": item["dir"],
- "px": _format_price(item["px"]),
- "sz": _compact_number(item["sz"]),
- "closed_pnl": _compact_number(item["closed_pnl"]),
- "fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(),
- }
- for item in data["recent_fills"]
- ]
- lines = [
- f"User: {data['user']}",
- f"Review window: {data['hours']} hours",
- f"Coin filter: {data['coin_filter'] or 'all traded coins'}",
- f"Fills analyzed: {summary['fill_count']}",
- f"Unique coins: {summary['unique_coins']}",
- f"Realized PnL: {_compact_number(summary['realized_pnl'])}",
- f"Fees: {_compact_number(summary['total_fees'])}",
- f"Net after fees: {_compact_number(summary['net_after_fees'])}",
- f"Win rate: {_format_percent(summary['win_rate_pct'])}",
- ]
- if data["findings"]:
- lines.extend(["", "Findings"])
- for finding in data["findings"]:
- lines.append(f"- {finding}")
- if coin_rows:
- lines.extend(
- [
- "",
- "Coin Breakdown",
- _render_table(
- [
- ("Coin", "coin"),
- ("Fills", "fills"),
- ("Net", "net"),
- ("Win Rate", "win_rate"),
- ("Trend", "trend"),
- ("Funding", "funding"),
- ("Bias", "bias"),
- ],
- coin_rows,
- ),
- ]
- )
- if recent_rows:
- lines.extend(
- [
- "",
- "Recent Fills",
- _render_table(
- [
- ("Time", "time"),
- ("Coin", "coin"),
- ("Dir", "dir"),
- ("Px", "px"),
- ("Sz", "sz"),
- ("Closed PnL", "closed_pnl"),
- ("Fee", "fee"),
- ],
- recent_rows,
- ),
- ]
- )
- return "\n".join(lines)
- def render_export(data: dict[str, Any]) -> str:
- summary = data["summary"]
- return "\n".join(
- [
- f"Coin: {data['coin']}",
- f"Interval: {data['interval']}",
- f"Hours: {data['hours']}",
- f"Schema: {data['schema_version']}",
- f"Output: {data['output_path']}",
- f"Candles: {summary['candle_count']}",
- f"Funding samples: {summary['funding_count']}",
- f"Window open -> close: {_format_price(summary.get('window_open'))} -> {_format_price(summary.get('window_close'))}",
- f"Price change: {_format_percent(summary.get('price_change_pct'))}",
- f"Average funding: {_format_fraction_percent(summary.get('average_funding_rate'))}",
- ]
- )
- def _add_json_flag(parser: argparse.ArgumentParser) -> None:
- parser.add_argument("--json", action="store_true", help="Print raw JSON output")
- def build_parser() -> argparse.ArgumentParser:
- parser = argparse.ArgumentParser(description="Hyperliquid CLI Tool for Hermes Agent")
- subparsers = parser.add_subparsers(dest="command", required=True)
- dexs = subparsers.add_parser("dexs", help="List available perpetual dexs")
- _add_json_flag(dexs)
- dexs.set_defaults(func=run_dexs, renderer=render_dexs)
- markets = subparsers.add_parser("markets", help="List perpetual market contexts")
- markets.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex")
- markets.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- markets.add_argument(
- "--sort",
- choices=["volume", "oi", "funding_abs", "change_abs", "name"],
- default="volume",
- help="Sort mode",
- )
- _add_json_flag(markets)
- markets.set_defaults(func=run_markets, renderer=render_markets)
- spots = subparsers.add_parser("spots", help="List spot market contexts")
- spots.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- spots.add_argument(
- "--sort",
- choices=["volume", "change_abs", "name"],
- default="volume",
- help="Sort mode",
- )
- _add_json_flag(spots)
- spots.set_defaults(func=run_spots, renderer=render_spots)
- candles = subparsers.add_parser("candles", help="Fetch candle history for a market")
- candles.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"')
- candles.add_argument("--interval", default="1h", help="Candle interval, e.g. 1m, 15m, 1h, 4h, 1d")
- candles.add_argument("--hours", type=float, default=24.0, help="Lookback window in hours")
- candles.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- _add_json_flag(candles)
- candles.set_defaults(func=run_candles, renderer=render_candles)
- funding = subparsers.add_parser("funding", help="Fetch funding history for a perp market")
- funding.add_argument("coin", help='Coin name, e.g. "BTC" or "mydex:COIN"')
- funding.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours")
- funding.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- _add_json_flag(funding)
- funding.set_defaults(func=run_funding, renderer=render_funding)
- l2 = subparsers.add_parser("l2", help="Inspect the current L2 book for a market")
- l2.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC"')
- l2.add_argument("--levels", type=int, default=10, help="Levels per side to display")
- l2.add_argument("--n-sig-figs", type=int, default=None, help="Optional server-side book aggregation")
- l2.add_argument("--mantissa", type=int, default=None, help="Optional mantissa when using nSigFigs")
- _add_json_flag(l2)
- l2.set_defaults(func=run_l2, renderer=render_l2)
- state = subparsers.add_parser("state", help="Inspect a user's perp account state")
- state.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
- state.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex")
- _add_json_flag(state)
- state.set_defaults(func=run_state, renderer=render_state)
- spot_balances = subparsers.add_parser("spot-balances", help="Inspect a user's spot token balances")
- spot_balances.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
- spot_balances.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- _add_json_flag(spot_balances)
- spot_balances.set_defaults(func=run_spot_balances, renderer=render_spot_balances)
- fills = subparsers.add_parser("fills", help="Inspect a user's recent fills")
- fills.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
- fills.add_argument("--hours", type=float, default=None, help="Optional time window; uses userFillsByTime")
- fills.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- fills.add_argument(
- "--aggregate-by-time",
- action="store_true",
- help="Aggregate partial fills when the API supports it",
- )
- _add_json_flag(fills)
- fills.set_defaults(func=run_fills, renderer=render_fills)
- orders = subparsers.add_parser("orders", help="Inspect a user's historical orders")
- orders.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
- orders.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
- _add_json_flag(orders)
- orders.set_defaults(func=run_orders, renderer=render_orders)
- review = subparsers.add_parser("review", help="Generate a lightweight post-trade review from recent fills")
- review.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
- review.add_argument("--coin", default="", help="Optional exact coin filter, e.g. BTC or PURR/USDC")
- review.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours")
- review.add_argument("--fills", type=int, default=50, help="Maximum fills to analyze")
- review.add_argument("--recent", type=int, default=10, help="Recent fills to display in the review")
- review.add_argument("--interval", default="1h", help="Candle interval for market context")
- review.add_argument(
- "--aggregate-by-time",
- action="store_true",
- help="Aggregate partial fills when the API supports it",
- )
- _add_json_flag(review)
- review.set_defaults(func=run_review, renderer=render_review)
- export = subparsers.add_parser("export", help="Export normalized candles and funding history to a JSON file")
- export.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"')
- export.add_argument("--interval", default="1h", help="Candle interval for the exported dataset")
- export.add_argument("--hours", type=float, default=168.0, help="Lookback window in hours")
- export.add_argument("--end-time-ms", type=int, default=None, help="Optional fixed end time for reproducible exports")
- export.add_argument("--output", default="", help="Path to the JSON export file")
- _add_json_flag(export)
- export.set_defaults(func=run_export, renderer=render_export)
- return parser
- def main(argv: Optional[list[str]] = None) -> int:
- parser = build_parser()
- args = parser.parse_args(argv)
- payload = args.func(args)
- if args.json:
- print(json.dumps(payload, indent=2))
- else:
- print(args.renderer(payload))
- return 0
- if __name__ == "__main__":
- raise SystemExit(main())
|