@senpi/runtime 3.0.146 → 3.0.149

package/dist/quant/engine/quantdesk/__main__.py

@@ -0,0 +1,281 @@
+"""`python3 -m quantdesk` — the runtime's fixed interface to the desk engine.
+
+  python3 -m quantdesk run --config <config.json> --out <result.json>
+  python3 -m quantdesk render --doc <run.json> [--section S ...] --out <result.json>
+
+The runtime owns this interface, not desk.py's flags. Results travel by FILE: the result document
+lands in --out, progress goes to stderr, and stdout carries nothing (desk.main's own prints are
+captured here). A result file always states `exit_code`; the process exits with the same code.
+The result file is strict JSON: a non-finite float (an all-winning bucket's profit factor is
+inf) is written as the string "Infinity", "-Infinity" or "NaN", and `render` reads them back.
+
+  0  {"document": <the desk's --json document, with cards and doc_version>}
+  1  {"refusal": ...}   Hyperliquid read failed (HLError)
+  2  {"refusal": ...}   invalid request (bad address, malformed config, argparse)
+  3  {"refusal": ...}   no perp activity in the window
+  4  {"refusal": ...}   not a trader's book (vault, or wider than the desk reads)
+  70 {"crash": ...}     anything else — a fault in the engine, never in the wallet
+"""
+import argparse
+import contextlib
+import io
+import json
+import math
+import os
+import sys
+import tempfile
+import time
+import traceback
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+if HERE not in sys.path:
+    sys.path.insert(0, HERE)
+
+import desk  # noqa: E402  flat on purpose: one module object, shared with the tests
+import render  # noqa: E402
+
+ENGINE_CRASH_EXIT = 70
+
+# Every key the runtime may send. An unknown key is refused rather than ignored: a typo such as
+# `froce` would otherwise run a different desk from the one the caller asked for, silently.
+CONFIG_KEYS = frozenset({"addresses", "days", "whose", "book", "force", "state_dir", "fixture"})
+
+# How a non-finite float crosses the file boundary. See _to_strict_json.
+_NON_FINITE_OUT = {math.inf: "Infinity", -math.inf: "-Infinity"}
+_NON_FINITE_IN = {"Infinity": math.inf, "-Infinity": -math.inf, "NaN": math.nan}
+
+
+# The longest TTL in hl_api (userRole / vaultDetails). A cache file older than this can never be a
+# hit again, and the desk's scratch (desk-*.json) is per-run; both are safe to delete past it.
+SCRATCH_MAX_AGE_S = 7 * 24 * 3600
+# The subdirectories of <state_dir> the engine writes and prunes. The runtime's registry files sit
+# next to them and are never touched here.
+SCRATCH_DIRS = ("cache", "engine")
+
+
+class ConfigError(ValueError):
+    """The runtime handed the engine a config it cannot act on — exit 2, never a traceback."""
+
+
+def build_argv(cfg):
+    """Translate the runtime's config into desk.main's argv.
+
+    The desk's own scratch state (desk-*.json) goes to <state_dir>/engine and its HTTP cache to
+    <state_dir>/cache, so the runtime's registry files under <state_dir> stay the only other thing
+    there. `fresh` is not passed: freshness is the runtime registry's rule, and a `run` without
+    --section/--deep always recomputes.
+    """
+    if not isinstance(cfg, dict):
+        raise ConfigError("config must be a JSON object")
+    unknown = sorted(set(cfg) - CONFIG_KEYS)
+    if unknown:
+        raise ConfigError(f"config has unknown keys {unknown}; expected only {sorted(CONFIG_KEYS)}")
+    # Real booleans only: a truthiness test turns the string "false" into --book / --force.
+    for flag in ("book", "force"):
+        if flag in cfg and not isinstance(cfg[flag], bool):
+            raise ConfigError(f"config.{flag} must be true or false")
+    if "fixture" in cfg and cfg["fixture"] is not None and not isinstance(cfg["fixture"], str):
+        raise ConfigError("config.fixture must be a path string")
+    addresses = cfg.get("addresses")
+    if not isinstance(addresses, list) or not addresses or not all(isinstance(a, str) and a for a in addresses):
+        raise ConfigError("config.addresses must be a non-empty list of addresses")
+    state_dir = cfg.get("state_dir")
+    if not isinstance(state_dir, str) or not state_dir:
+        raise ConfigError("config.state_dir is required")
+    whose = cfg.get("whose", "mine")
+    if whose not in ("mine", "other"):
+        raise ConfigError('config.whose must be "mine" or "other"')
+    days = cfg.get("days", 90)
+    if isinstance(days, bool) or not isinstance(days, int) or days < 1:
+        raise ConfigError("config.days must be a positive integer")
+    argv = ["--book", *addresses] if (cfg.get("book") or len(addresses) > 1) else [addresses[0]]
+    argv += ["--other" if whose == "other" else "--mine", "--days", str(days)]
+    if cfg.get("force"):
+        argv.append("--force")
+    argv += ["--state-dir", os.path.join(state_dir, "engine"), "--cache", os.path.join(state_dir, "cache"), "--json"]
+    if cfg.get("fixture"):
+        argv += ["--fixture", cfg["fixture"], "--dry"]
+    return argv
+
+
+def _to_strict_json(obj):
+    """Replace non-finite floats with the strings "Infinity", "-Infinity" and "NaN", recursively.
+
+    Why: the desk's figures legitimately include infinity — a profit factor on a bucket with no
+    losing trade is `float("inf")` (metrics, strategy_read, timing, market, score, opportunities,
+    deep) — and Python's json writes that as the bare token `Infinity`, which is not JSON. Node's
+    `JSON.parse` rejects the whole file, so the runtime would read every such successful desk as an
+    engine fault. Strings keep the value readable on both sides; `_from_strict_json` restores them
+    before anything in Python renders the document again.
+    """
+    if isinstance(obj, float):
+        if math.isnan(obj):
+            return "NaN"
+        return _NON_FINITE_OUT.get(obj, obj)
+    if isinstance(obj, dict):
+        return {k: _to_strict_json(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_to_strict_json(v) for v in obj]
+    return obj
+
+
+def _from_strict_json(obj):
+    """The inverse of `_to_strict_json`: the three marker strings become float inf/-inf/nan again.
+
+    Why: render.py formats `inf` as "∞" and compares against `float("inf")`; a re-render from a
+    stored run must produce the same Markdown as the in-process render did. The cost is that a
+    genuine string field whose whole value is "NaN" or "Infinity" would be read back as a float; no
+    field of the desk document is such a string (coins, labels and prose never are).
+    """
+    if isinstance(obj, str):
+        return _NON_FINITE_IN.get(obj, obj)
+    if isinstance(obj, dict):
+        return {k: _from_strict_json(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_from_strict_json(v) for v in obj]
+    return obj
+
+
+def _non_finite_card_fields(doc):
+    """Card fields holding a non-finite number. Always empty today (a leak's usd is a finite sum);
+    checked so a future card never ships "Infinity" as a dollar figure to a client."""
+    return [f"{c.get('id')}.{k}" for c in doc.get("cards") or [] for k, v in c.items()
+            if isinstance(v, float) and not math.isfinite(v)]
+
+
+def _write(out_path, obj):
+    """Write the result file atomically (write-then-rename), as STRICT JSON.
+
+    `allow_nan=False` after `_to_strict_json` makes a missed non-finite float a loud ValueError here
+    rather than a file the runtime cannot parse. The rename means the runtime never reads a
+    half-written result.
+    """
+    text = json.dumps(_to_strict_json(obj), allow_nan=False)
+    d = os.path.dirname(out_path) or "."
+    os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=d, prefix=".quantdesk.", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        os.replace(tmp, out_path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def prune_scratch(state_dir, now=None, max_age_s=SCRATCH_MAX_AGE_S):
+    """Delete files older than `max_age_s` under <state_dir>/cache and <state_dir>/engine.
+
+    Why: hl_api never deletes a cache file — it only ignores one past its TTL — and its keys are
+    time-bucketed (`now_ms` floored to 5 minutes goes into every expensive read's body), so every
+    desk writes new keys and the cache grows without bound on a long-lived agent box. Seven days is
+    the longest TTL, so nothing deleted here could still have been a hit.
+
+    Best-effort by contract: an unreadable directory or a file that cannot be deleted is skipped,
+    never raised — pruning is housekeeping and is never a reason for a desk to fail. Prints
+    `[quant-desk] cache: pruned N files` to stderr (the progress stream) only when N > 0, so a
+    normal run's progress stays unchanged; stdout is never written.
+
+    Returns the number of files deleted.
+    """
+    cutoff = (time.time() if now is None else now) - max_age_s
+    pruned = 0
+    for sub in SCRATCH_DIRS:
+        for root, _dirs, files in os.walk(os.path.join(state_dir, sub)):
+            for name in files:
+                path = os.path.join(root, name)
+                try:
+                    if os.path.getmtime(path) < cutoff:
+                        os.unlink(path)
+                        pruned += 1
+                except OSError:
+                    continue
+    if pruned:
+        print(f"[quant-desk] cache: pruned {pruned} files", file=sys.stderr, flush=True)
+    return pruned
+
+
+def run(config_path, out_path):
+    """Run one desk from a config file and write the result file. Returns the exit code.
+
+    Before the desk starts, scratch older than seven days is pruned (`prune_scratch`); a failure
+    there never changes the outcome of the run.
+    """
+    try:
+        with open(config_path, encoding="utf-8") as fh:
+            cfg = json.load(fh)
+        argv = build_argv(cfg)
+    except (OSError, ValueError) as e:            # ConfigError and JSONDecodeError are ValueErrors
+        _write(out_path, {"exit_code": 2, "refusal": {"error": f"invalid engine config: {e}"}})
+        return 2
+    try:
+        prune_scratch(cfg["state_dir"])
+    except Exception:  # noqa: BLE001  housekeeping never fails a desk
+        pass
+    buf = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(buf):
+            rc = desk.main(argv)
+    except SystemExit as e:                       # argparse refusing the argv
+        rc = e.code if isinstance(e.code, int) else 2
+    except Exception as e:  # noqa: BLE001
+        traceback.print_exc()
+        _write(out_path, {"exit_code": ENGINE_CRASH_EXIT,
+                          "crash": {"error": f"{type(e).__name__}: {e}",
+                                    "traceback": traceback.format_exc().splitlines()[-20:]}})
+        return ENGINE_CRASH_EXIT
+    text = buf.getvalue().strip()
+    try:
+        body = json.loads(text) if text else None
+    except ValueError:
+        body = None
+    if rc == 0:
+        if not isinstance(body, dict):
+            _write(out_path, {"exit_code": ENGINE_CRASH_EXIT,
+                              "crash": {"error": "the desk finished but printed no JSON document", "stdout_tail": text[-2000:]}})
+            return ENGINE_CRASH_EXIT
+        bad = _non_finite_card_fields(body)
+        if bad:
+            _write(out_path, {"exit_code": ENGINE_CRASH_EXIT,
+                              "crash": {"error": f"cards carry non-finite figures: {bad}"}})
+            return ENGINE_CRASH_EXIT
+        _write(out_path, {"exit_code": 0, "document": body})
+        return 0
+    _write(out_path, {"exit_code": rc, "refusal": body if isinstance(body, dict) else {"error": text[-2000:] or "no detail"}})
+    return rc
+
+
+def render_doc(doc_path, sections, out_path):
+    """Re-render sections from a stored run (or a bare document). No network, no recompute."""
+    try:
+        with open(doc_path, encoding="utf-8") as fh:
+            stored = json.load(fh)
+    except (OSError, ValueError) as e:
+        _write(out_path, {"exit_code": 2, "refusal": {"error": f"unreadable stored run: {e}"}})
+        return 2
+    doc = stored.get("document") if isinstance(stored, dict) and "document" in stored else stored
+    if not isinstance(doc, dict):
+        _write(out_path, {"exit_code": 2, "refusal": {"error": "the stored run has no document"}})
+        return 2
+    _write(out_path, {"exit_code": 0, "markdown": render.render(_from_strict_json(doc), sections or None)})
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="python3 -m quantdesk", description="Senpi quant desk engine (runtime interface)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("run", help="run one desk from a config file")
+    r.add_argument("--config", required=True)
+    r.add_argument("--out", required=True)
+    d = sub.add_parser("render", help="render sections of a stored run")
+    d.add_argument("--doc", required=True)
+    d.add_argument("--section", action="append", choices=render.SECTIONS)
+    d.add_argument("--out", required=True)
+    a = ap.parse_args(argv)
+    if a.cmd == "run":
+        return run(a.config, a.out)
+    return render_doc(a.doc, a.section, a.out)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/quant/engine/quantdesk/_version.py

@@ -0,0 +1,24 @@
+"""The engine's version is the runtime package's version.
+
+The desk used to carry its own literal (1.38.0), pinned by a test to the skill's frontmatter so a
+stale install was visible. Inside @senpi-ai/runtime the engine cannot be stale on its own: it ships
+in the same tarball as the TypeScript that spawns it. Reading package.json (four levels up from
+here in both `src/quant/engine/quantdesk` and `dist/quant/engine/quantdesk`) keeps one number, and
+the release job's version bump cannot break a pin.
+"""
+import json
+import os
+
+_PKG = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..", "..", "package.json")
+
+
+def _read():
+    try:
+        with open(_PKG, encoding="utf-8") as fh:
+            v = json.load(fh).get("version")
+        return v if isinstance(v, str) and v else "0.0.0"
+    except (OSError, ValueError):
+        return "0.0.0"
+
+
+VERSION = _read()

package/dist/quant/engine/quantdesk/benchmark.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Recompute benchmark.json (next to the engine) — the whale medians the desk compares a trader against.
+
+With `SENPI_AUTH_TOKEN` (the only source that works for whales): the cohort is Senpi discovery's ≥ $1M-realized
+ranking and each member's closed positions come from `discovery_get_trader_history` — complete. Without a
+token the script falls back to the public leaderboard's large accounts read through the public engine, but
+whales are TWAP-heavy and the public endpoints keep only the most recent slices, so their round trips come
+back 0–1 per wallet: that run is diagnostic only, and the desk hides the whale-median table when the
+benchmark has fewer than 5 members with ≥ 10 trades.
+
+  SENPI_AUTH_TOKEN=… python3 benchmark.py [--n 40] [--days 90] [--out benchmark.json (next to the engine)]
+"""
+# Copyright 2026 Senpi (https://senpi.ai) — Apache-2.0
+import argparse
+import json
+import os
+import statistics
+import sys
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import hl_api  # noqa: E402
+import metrics  # noqa: E402
+import senpi_history  # noqa: E402
+import smart_money  # noqa: E402
+from roundtrips import episodes_from_fills  # noqa: E402
+
+KEYS = ("win_rate", "profit_factor", "hold_winners_h", "hold_losers_h", "hold_ratio", "cost_ratio", "taker_share", "size_cv", "payoff_ratio", "long_share")
+
+
+def member(hl, addr, days, mcp=None):
+    win_start = hl.now_ms - days * hl_api.DAY_MS
+    start = hl.now_ms - (days + 60) * hl_api.DAY_MS
+    fills = hl_api.merge_fills(hl.fills(addr, start), hl.twap_slices(addr, start))
+    closed, opened = episodes_from_fills(fills)
+    if mcp is not None:
+        rows = senpi_history.fetch(mcp, addr, win_start, {})
+        if rows:
+            closed = rows
+    tr = metrics.track_record(closed, opened, hl.funding(addr, win_start), hl.info({"type": "userFees", "user": addr}), win_start)
+    out = {k: tr.get(k) for k in KEYS}
+    out.update(trades=tr["trades"], complete_trades=tr["complete_trades"], liquidations=tr["liquidations"], fills=len(fills))
+    out["coverage"] = metrics.coverage(closed, opened)["overall"]
+    return out
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=40); ap.add_argument("--days", type=int, default=90)
+    ap.add_argument("--out", default=os.path.join(HERE, "benchmark.json"))
+    a = ap.parse_args(argv)
+    hl = hl_api.HL(timeout=90)
+    mcp = None
+    if os.environ.get("SENPI_AUTH_TOKEN"):
+        from mcp_client import MCPClient
+        mcp = MCPClient()
+        cohort = smart_money.senpi_cohort(mcp, {})[: a.n * 2]
+        print(f"cohort: Senpi discovery, {len(cohort)} wallets with ≥ $1M realized", file=sys.stderr)
+    else:
+        cohort = hl_api.public_cohort(hl.leaderboard(), n=a.n * 3)   # candidates; accounts with no fills are skipped
+        print("cohort: public leaderboard — diagnostic only for whales (see the docstring)", file=sys.stderr)
+    members, t0 = [], time.time()
+    for i, addr in enumerate(cohort):
+        if len(members) >= a.n:
+            break
+        try:
+            m = member(hl, addr, a.days, mcp)
+            if not m["fills"] and not m["trades"]:
+                print(f"{i + 1:2d} no fills — skipped", file=sys.stderr, flush=True)
+                continue
+            members.append(m)
+            print(f"{len(members):2d}/{a.n} trades={m['trades']:3d} complete={m['complete_trades']:3d} coverage={m['coverage']}", file=sys.stderr, flush=True)
+        except hl_api.HLError as e:
+            print(f"{i + 1:2d} failed: {e}", file=sys.stderr, flush=True)
+        time.sleep(0.5)
+    valid = [m for m in members if m["trades"] >= 10]
+    def med(k):
+        xs = [m[k] for m in valid if m[k] is not None and m[k] != float("inf")]
+        return statistics.median(xs) if xs else None
+    bench = {k: med(k) for k in KEYS}
+    bench.update(n=len(valid), cohort=("Senpi discovery — wallets with ≥ $1M realized" if mcp is not None else f"top-{a.n} profitable accounts ≥ $1M on Hyperliquid's leaderboard"),
+                 computed_at=time.strftime("%Y-%m-%d"), window_days=a.days, engine="quant-desk roundtrips/metrics", seconds=round(time.time() - t0))
+    with open(a.out, "w") as fh:
+        json.dump({"benchmark": bench, "members": members}, fh, indent=1)
+    print(json.dumps(bench, indent=1))
+
+
+if __name__ == "__main__":
+    main()

package/dist/quant/engine/quantdesk/book.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""One desk over SEVERAL wallets — a senpi user's whole book, not one subwallet of it.
+
+A senpi user does not have "a wallet". They have a funding wallet that never trades and N strategy
+subwallets that do, opened and closed as strategies come and go. Running the desk on one of them
+scores one strategy; the reader asked about their trading. `--book 0xA 0xB 0xC` reads each wallet,
+then UNIONS them into a single `tr_raw` the rest of the desk cannot tell from one account's.
+
+Union, not concatenation — four of the keys need real arithmetic:
+
+* **episodes** are built PER WALLET and then unioned. `episodes_from_fills` tracks position per coin
+  through `startPosition`; concatenating two wallets that both trade BTC interleaves two position
+  tracks into one and the reconstruction is garbage. This is the reason this module exists.
+* **portfolio** series are SUMMED on a union timestamp grid, step-interpolated. Before a wallet's
+  first sample it contributes 0 (it did not exist); after its last it carries its final value (a
+  closed strategy keeps whatever P&L it ended with). Equity and cumulative P&L are both correct
+  under that rule, and both are denominators — drawdown, return-on-equity, beta.
+* **ledger** transfers BETWEEN wallets in the set are dropped. Moving $10k from one of your
+  strategies to another is not a deposit and not a withdrawal; left in, it lands in `flows()` twice
+  with opposite signs on the same book and makes the equity curve step for no reason.
+* **dailyUserVlm** is summed by date, because the coverage diagnostic divides observed volume by it.
+  One wallet's denominator against three wallets' numerator reads as 300% coverage.
+
+Copyright 2026 Senpi (https://senpi.ai) — Apache-2.0
+"""
+import collections
+
+from roundtrips import episodes_from_fills
+
+
+def _f(x, d=0.0):
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return d
+
+
+def _sum_series(per_wallet):
+    """Sum N [(t, value)] series onto the union of their timestamps.
+
+    Step-interpolated: each wallet holds its last value between its own samples. Outside its range
+    it contributes 0 BEFORE it opened and its final value AFTER it closed — which is what a wallet
+    that did not exist yet, and one that has been emptied, actually contributed to the book."""
+    grid = sorted({t for s in per_wallet for t, _ in s})
+    if not grid:
+        return []
+    cursors = [0] * len(per_wallet)
+    held = [0.0] * len(per_wallet)
+    out = []
+    for t in grid:
+        for i, s in enumerate(per_wallet):
+            while cursors[i] < len(s) and s[cursors[i]][0] <= t:
+                held[i] = s[cursors[i]][1]; cursors[i] += 1
+        out.append([t, sum(held)])
+    return out
+
+
+def _merge_portfolio(portfolios):
+    """Sum every window of HL's `portfolio` response across wallets, series by series."""
+    names, by_name = [], collections.defaultdict(list)
+    for p in portfolios:
+        for name, win in (p or []):
+            if name not in by_name:
+                names.append(name)
+            by_name[name].append(win or {})
+    out = []
+    for name in names:
+        wins = by_name[name]
+        win = {}
+        for key in ("accountValueHistory", "pnlHistory"):
+            series = [[(t, _f(v)) for t, v in (w.get(key) or [])] for w in wins]
+            if any(series):
+                # back to HL's own shape: [ms, "string"] — every reader of this goes through _f()
+                win[key] = [[t, str(v)] for t, v in _sum_series(series)]
+        vlm = sum(_f(w.get("vlm")) for w in wins)
+        if vlm:
+            win["vlm"] = str(vlm)
+        out.append([name, win])
+    return out
+
+
+def _merge_fees(scheds):
+    """The fee SCHEDULE of the wallet that traded most, with `dailyUserVlm` summed across all of them.
+
+    Rates are a tier, not a quantity: they do not add. Every dollar figure on the desk is anchored on
+    fees actually paid (summed from fills) and the schedule is only used to APPORTION those dollars
+    between taker and maker, so the busiest wallet's tier is the right representative. The daily
+    volume table is a quantity and does add — it is the denominator of the coverage diagnostic."""
+    live = [s for s in scheds if s]
+    if not live:
+        return None
+    def traded(s):
+        return sum(_f(d.get("userCross")) + _f(d.get("userAdd")) for d in (s.get("dailyUserVlm") or []))
+    out = dict(max(live, key=traded))
+    by_date = collections.defaultdict(lambda: [0.0, 0.0])
+    for s in live:
+        for d in (s.get("dailyUserVlm") or []):
+            row = by_date[d.get("date")]
+            row[0] += _f(d.get("userCross")); row[1] += _f(d.get("userAdd"))
+    if by_date:
+        out["dailyUserVlm"] = [{"date": d, "userCross": str(c), "userAdd": str(m)}
+                               for d, (c, m) in sorted(by_date.items()) if d]
+    return out
+
+
+def _merge_clearinghouse(states, addrs=None):
+    """Positions concatenated, margin summed. A merged book's margin is the sum of its wallets'.
+
+    Each position is stamped with the wallet it came from. Two strategies can hold the same coin,
+    and the protection audit matches resting stops to positions — by coin alone it would credit one
+    wallet's stop to the other's bare position and call a naked position protected."""
+    live = [(a, s) for a, s in zip(addrs or [None] * len(states), states) if s]
+    if not live:
+        return None
+    pos = []
+    for a, s in live:
+        for ap in (s.get("assetPositions") or []):
+            ap = dict(ap); ap["position"] = dict(ap["position"], wallet=a)
+            pos.append(ap)
+    live = [s for _a, s in live]
+    out = {"assetPositions": pos, "time": max((s.get("time") or 0) for s in live)}
+    for key in ("marginSummary", "crossMarginSummary"):
+        parts = [s.get(key) or {} for s in live]
+        fields = {k for p in parts for k in p}
+        if fields:
+            out[key] = {k: str(sum(_f(p.get(k)) for p in parts)) for k in fields}
+    for key in ("withdrawable", "crossMaintenanceMarginUsed"):
+        out[key] = str(sum(_f(s.get(key)) for s in live))
+    return out
+
+
+def _merge_spot(states):
+    live = [s for s in states if s]
+    if not live:
+        return None
+    bal = collections.defaultdict(lambda: [0.0, 0.0])
+    for s in live:
+        for b in (s.get("balances") or []):
+            row = bal[b.get("coin")]
+            row[0] += _f(b.get("total")); row[1] += _f(b.get("hold"))
+    return {"balances": [{"coin": c, "total": str(t), "hold": str(h)} for c, (t, h) in sorted(bal.items())]}
+
+
+def _internal(ledger, wallets):
+    """Drop sends whose BOTH ends are wallets of this book — an internal move, not a flow."""
+    out = []
+    for x in ledger or []:
+        d = x.get("delta") or {}
+        if d.get("type") == "send":
+            if str(d.get("destination") or "").lower() in wallets and str(d.get("user") or "").lower() in wallets:
+                continue
+        out.append(x)
+    return out
+
+
+def read(hl, addrs, days=90, progress=None):
+    """Read every wallet and return `(tr_raw, closed, opened, per_wallet)` for the union.
+
+    Sequential by design: Hyperliquid's Info API 429s on parallel reads from one client, and a
+    rate-limited wallet would silently drop out of somebody's book total."""
+    addrs = [a.strip().lower() for a in addrs]
+    seen, uniq = set(), []
+    for a in addrs:
+        if a not in seen:
+            seen.add(a); uniq.append(a)
+    raws, closed, opened, per_wallet = [], [], [], []
+    for i, a in enumerate(uniq, 1):
+        if progress:
+            progress(f"[quant-desk]   · wallet {i} of {len(uniq)}: {a[:6]}…{a[-4:]} …")
+        tr = hl.trader(a, days=days)
+        raws.append(tr)
+        c, o = episodes_from_fills(tr["fills"])
+        for e in c + o:
+            e["wallet"] = a
+        closed.extend(c); opened.extend(o)
+        per_wallet.append(dict(address=a, fills=len(tr["fills"]), closed=len(c), open=len(o)))
+    first = raws[0]
+    wallets = set(uniq)
+    merged = {
+        "address": uniq[0], "wallets": uniq,
+        "now_ms": first["now_ms"], "window_start_ms": first["window_start_ms"],
+        "fetch_start_ms": first["fetch_start_ms"], "days": days,
+        "clearinghouseState": _merge_clearinghouse([r["clearinghouseState"] for r in raws], uniq),
+        "clearinghouseState_xyz": _merge_clearinghouse([r.get("clearinghouseState_xyz") for r in raws], uniq),
+        "frontendOpenOrders": [dict(o, wallet=a) for a, r in zip(uniq, raws) for o in (r["frontendOpenOrders"] or [])],
+        "frontendOpenOrders_xyz": [dict(o, wallet=a) for a, r in zip(uniq, raws) for o in (r.get("frontendOpenOrders_xyz") or [])],
+        "spotClearinghouseState": _merge_spot([r.get("spotClearinghouseState") for r in raws]),
+        "fills": sorted((f for r in raws for f in r["fills"]), key=lambda f: f["time"]),
+        "userFunding": sorted((dict(x, wallet=a) for a, r in zip(uniq, raws) for x in (r["userFunding"] or [])),
+                              key=lambda x: x["time"]),
+        "userFees": _merge_fees([r["userFees"] for r in raws]),
+        "userFees_xyz": _merge_fees([r.get("userFees_xyz") for r in raws]),
+        "portfolio": _merge_portfolio([r["portfolio"] for r in raws]),
+        "ledger": sorted(_internal([x for r in raws for x in (r["ledger"] or [])], wallets), key=lambda x: x["time"]),
+    }
+    closed.sort(key=lambda e: e.get("close_time") or e.get("open_time") or 0)
+    return merged, closed, opened, per_wallet