async-hyperliquid 1.0.0rc1__tar.gz → 1.2.0__tar.gz

{async_hyperliquid-1.0.0rc1 → async_hyperliquid-1.2.0}/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-11-03
+
+### Added
+
+- Add `fast=True` to `cancel_order()`, `cancel_orders()`, `cancel_by_cloid()`, and
+  `cancel_orders_by_cloid()` to send Hyperliquid's fast-cancel `f` flag; the flag
+  is omitted when `fast=False`. The exchange rejects fast cancels of trigger
+  orders per status, so `fast` stays opt-in.
+- Add testnet integration coverage for fast cancels and a diagnostic
+  `benchmarks/fast_cancel.py` comparing fast and non-fast cancel latency.
+
+## [1.1.0] - 2026-09-14
+
+### Added
+
+- Add `InfoClient.extra_agents()` with typed API-wallet responses.
+- Add `reversed=True` to `InfoClient.user_fills()` time-range queries to request
+  the newest fills first; `start_time` is required when enabled.
+
+### Fixed
+
+- Cover ascending and mixed-order fill responses to detect unintended client-side
+  sorting, and verify reversed fill queries against complete reference windows.
+
+## [1.0.0] - 2026-08-17
+
+### Added
+
+- Publish comprehensive Read the Docs documentation for installation, Info and
+  Exchange workflows, routing, market and asset mapping, reconciliation,
+  migration, project ownership, licensing, and the public API reference.
+- Add a complete Simplified Chinese documentation build using Sphinx gettext,
+  while preserving Python identifiers, signatures, types, code, and autodoc
+  content in English.
+
+### Changed
+
+- Promote the 1.0 API from release candidate to stable without additional
+  runtime contract changes.
+- Gate English and Simplified Chinese documentation in CI, release validation,
+  and source-distribution tests with warnings treated as errors.
+- Publish GitHub Release notes from the exact matching CHANGELOG section and
+  verify the body before and after immutable release publication.
+- Run artifact download actions on the Node 24 runtime.
+
 ## [1.0.0rc1] - 2026-08-04
 
 ### Added

async_hyperliquid-1.2.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: async-hyperliquid
+Version: 1.2.0
+Summary: Async Hyperliquid client using aiohttp
+Keywords: dex,hyperliquid,async,aiohttp,trading,cryptocurrency,defi
+Author: Yuki
+Author-email: Yuki <yuqi.lyle@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: aiohttp
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp>=3.14.3,<4.0.0
+Requires-Dist: msgpack>=1.2.1,<2.0.0
+Requires-Dist: eth-account>=0.13.7,<0.14.0
+Requires-Dist: eth-utils>=5.3.1,<6.0.0
+Requires-Dist: coincurve>=21.0.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/owlyfi/async-hyperliquid
+Project-URL: Documentation, https://async-hyperliquid.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/owlyfi/async-hyperliquid
+Project-URL: Issues, https://github.com/owlyfi/async-hyperliquid/issues
+Project-URL: Changelog, https://github.com/owlyfi/async-hyperliquid/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Async Hyperliquid
+
+[![CI](https://github.com/owlyfi/async-hyperliquid/actions/workflows/ci.yml/badge.svg)](https://github.com/owlyfi/async-hyperliquid/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/async-hyperliquid/badge/?version=latest)](https://async-hyperliquid.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/async-hyperliquid.svg?v=1.2.0)](https://pypi.org/project/async-hyperliquid/)
+
+`async-hyperliquid` is a typed, asynchronous Python client for the Hyperliquid
+REST API. It provides credential-free market and account queries through
+`InfoClient`, plus authenticated order workflows through `AsyncHyperliquid`.
+The client uses `aiohttp`, keeps protocol-shaped responses as `TypedDict`, and
+supports explicit mainnet and testnet routing.
+
+## Installation
+
+```bash
+pip install async-hyperliquid
+```
+
+## Read market data
+
+```python
+import asyncio
+
+from async_hyperliquid import InfoClient
+from async_hyperliquid.types import Network
+
+
+async def main() -> None:
+    async with InfoClient(network=Network.MAINNET) as client:
+        print(await client.mid_price("BTC"))
+
+
+asyncio.run(main())
+```
+
+## Place a testnet order
+
+Use a dedicated API-wallet key and start on testnet. This submits a signed
+market order.
+
+```python
+import asyncio
+import os
+
+from async_hyperliquid import AsyncHyperliquid
+from async_hyperliquid.types import Network
+
+
+async def main() -> None:
+    async with AsyncHyperliquid(
+        os.environ["HL_ACCOUNT_ADDRESS"],
+        os.environ["HL_SIGNING_KEY"],
+        network=Network.TESTNET,
+    ) as client:
+        result = await client.place_order("BTC", True, 0.001, 0, is_market=True)
+        if result["status"] == "err":
+            raise RuntimeError(result["response"])
+        status = result["response"]["data"]["statuses"][0]
+        if isinstance(status, dict) and "error" in status:
+            raise RuntimeError(status["error"])
+        print(status)
+
+
+asyncio.run(main())
+```
+
+Learn more in the [Read the Docs documentation](https://async-hyperliquid.readthedocs.io/en/latest/),
+[API reference](https://async-hyperliquid.readthedocs.io/en/latest/reference/index.html),
+[migration guide](https://async-hyperliquid.readthedocs.io/en/latest/migration-0.5-to-1.0.html),
+[changelog](CHANGELOG.md), and [license](LICENSE).
+
+## Benchmarks
+
+The overall signing benchmark values below are from a parity-gated `1.0.0rc1`
+local CPU reference run. They are not network latency or exchange throughput.
+See the detailed [benchmarks/README.md](benchmarks/README.md) manual for the
+full methodology, parity gate, and per-operation results.
+
+<!-- signing-benchmark:overall:start -->
+| Library | Geometric-mean throughput | Relative to SDK |
+|---|---:|---:|
+| async-hyperliquid | 24,641 ops/s | 1.460x |
+| Official SDK | 16,874 ops/s | 1.000x |
+| CCXT | 803 ops/s | 0.0476x |
+
+The geometric mean gives each of the five operations equal weight, preventing
+the faster `action_hash` workload from dominating the score.
+<!-- signing-benchmark:overall:end -->

async_hyperliquid-1.2.0/README.md

@@ -0,0 +1,88 @@
+# Async Hyperliquid
+
+[![CI](https://github.com/owlyfi/async-hyperliquid/actions/workflows/ci.yml/badge.svg)](https://github.com/owlyfi/async-hyperliquid/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/async-hyperliquid/badge/?version=latest)](https://async-hyperliquid.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/async-hyperliquid.svg?v=1.2.0)](https://pypi.org/project/async-hyperliquid/)
+
+`async-hyperliquid` is a typed, asynchronous Python client for the Hyperliquid
+REST API. It provides credential-free market and account queries through
+`InfoClient`, plus authenticated order workflows through `AsyncHyperliquid`.
+The client uses `aiohttp`, keeps protocol-shaped responses as `TypedDict`, and
+supports explicit mainnet and testnet routing.
+
+## Installation
+
+```bash
+pip install async-hyperliquid
+```
+
+## Read market data
+
+```python
+import asyncio
+
+from async_hyperliquid import InfoClient
+from async_hyperliquid.types import Network
+
+
+async def main() -> None:
+    async with InfoClient(network=Network.MAINNET) as client:
+        print(await client.mid_price("BTC"))
+
+
+asyncio.run(main())
+```
+
+## Place a testnet order
+
+Use a dedicated API-wallet key and start on testnet. This submits a signed
+market order.
+
+```python
+import asyncio
+import os
+
+from async_hyperliquid import AsyncHyperliquid
+from async_hyperliquid.types import Network
+
+
+async def main() -> None:
+    async with AsyncHyperliquid(
+        os.environ["HL_ACCOUNT_ADDRESS"],
+        os.environ["HL_SIGNING_KEY"],
+        network=Network.TESTNET,
+    ) as client:
+        result = await client.place_order("BTC", True, 0.001, 0, is_market=True)
+        if result["status"] == "err":
+            raise RuntimeError(result["response"])
+        status = result["response"]["data"]["statuses"][0]
+        if isinstance(status, dict) and "error" in status:
+            raise RuntimeError(status["error"])
+        print(status)
+
+
+asyncio.run(main())
+```
+
+Learn more in the [Read the Docs documentation](https://async-hyperliquid.readthedocs.io/en/latest/),
+[API reference](https://async-hyperliquid.readthedocs.io/en/latest/reference/index.html),
+[migration guide](https://async-hyperliquid.readthedocs.io/en/latest/migration-0.5-to-1.0.html),
+[changelog](CHANGELOG.md), and [license](LICENSE).
+
+## Benchmarks
+
+The overall signing benchmark values below are from a parity-gated `1.0.0rc1`
+local CPU reference run. They are not network latency or exchange throughput.
+See the detailed [benchmarks/README.md](benchmarks/README.md) manual for the
+full methodology, parity gate, and per-operation results.
+
+<!-- signing-benchmark:overall:start -->
+| Library | Geometric-mean throughput | Relative to SDK |
+|---|---:|---:|
+| async-hyperliquid | 24,641 ops/s | 1.460x |
+| Official SDK | 16,874 ops/s | 1.000x |
+| CCXT | 803 ops/s | 0.0476x |
+
+The geometric mean gives each of the five operations equal weight, preventing
+the faster `action_hash` workload from dominating the score.
+<!-- signing-benchmark:overall:end -->

{async_hyperliquid-1.0.0rc1 → async_hyperliquid-1.2.0}/benchmarks/README.md

@@ -207,6 +207,30 @@ Artifacts: [sanitized JSON](results/20260805T192621Z/report.json), [sample CSV](
 These measurements describe one testnet run, not exchange capacity. Shared-IP traffic, geography, testnet load, dependency versions, and network conditions can change results.
 <!-- live-exchange-benchmark:detail:end -->
 
+## Fast-cancel benchmark
+
+`benchmarks/fast_cancel.py` compares single-order `cancel_order()` latency with
+`fast=False` and `fast=True` on testnet. It uses the same `.env.local`
+credentials and safety checks as the live Exchange benchmark (testnet only,
+`HL_SK` must derive `HL_AK`, roles validated before any order).
+
+Each round places `--orders` resting BTC ALO buys at `mid * 0.9` (about 12 USDC
+each) in one batch, then cancels them sequentially, alternating the two methods;
+the method that goes first swaps every round. Only the cancel request is timed,
+pacing sleeps excluded. Any non-success cancel aborts the run, and remaining
+orders are cancelled on exit.
+
+```bash
+uv run --frozen --group benchmark python benchmarks/fast_cancel.py \
+  --rounds 30 --warmups 3 --orders 10
+```
+
+The output is a plain-text table of n, mean, p50, p90, p99, min and max in ms.
+Hyperliquid currently documents no effect for `fast` other than rejecting
+trigger orders, so the two methods are expected to match today; the benchmark
+is a baseline for the future mempool-priority upgrade. It is diagnostic only
+and does not produce publishable artifacts.
+
 ## Signing benchmark
 
 This benchmark compares Hyperliquid signing and order-payload construction in
@@ -372,15 +396,18 @@ divided by the provider aggregate median, so higher is better.
 The overall score gives each of the five operations equal weight. It is the
 geometric mean of their aggregate throughputs:
 
+<!-- signing-benchmark:overall:start -->
 | Library | Geometric-mean throughput | Relative to SDK |
 |---|---:|---:|
 | async-hyperliquid | 24,641 ops/s | 1.460x |
 | Official SDK | 16,874 ops/s | 1.000x |
 | CCXT | 803 ops/s | 0.0476x |
 
-The geometric mean prevents the much faster `action_hash` workload from
-dominating the result merely because it has a larger absolute ops/s value. The
-same five workloads, versions, and weighting must be used for comparisons.
+The geometric mean gives each of the five operations equal weight, preventing
+the faster `action_hash` workload from dominating the score.
+<!-- signing-benchmark:overall:end -->
+
+The same five workloads, versions, and weighting must be used for comparisons.
 
 ## Correctness verification
 

async_hyperliquid-1.2.0/benchmarks/fast_cancel.py

@@ -0,0 +1,178 @@
+"""Compare single-order cancel latency with fast=False and fast=True on testnet.
+
+Each round places ``--orders`` resting BTC ALO buys far below mid in one batch,
+then cancels them one at a time, alternating fast=False / fast=True. The method
+that goes first swaps every round. Only the cancel request itself is timed;
+pacing sleeps are excluded. Any non-success cancel invalidates the run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import math
+import os
+import statistics
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from time import perf_counter_ns
+
+if __package__ in (None, ""):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from async_hyperliquid import AsyncHyperliquid
+from async_hyperliquid.types import (
+    CancelOrder,
+    CancelOrderResponse,
+    Network,
+    PlaceOrderRequest,
+    TimeInForce,
+    limit_order_type,
+)
+from benchmarks.live.models import MIN_INTERVAL_NS, BenchmarkFailure
+from benchmarks.live.pacing import WeightedPacer
+from benchmarks.live.preflight import Credentials, validate_roles
+
+COIN = "BTC"
+NOTIONAL_USDC = 12
+PRICE_RATIO = 0.9
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--rounds", type=int, default=30)
+    parser.add_argument("--warmups", type=int, default=3)
+    parser.add_argument("--orders", type=int, default=10, help="even, per round")
+    parser.add_argument("--interval-ms", type=int, default=250)
+    args = parser.parse_args(argv)
+    if args.rounds < 1 or args.warmups < 0:
+        parser.error("--rounds must be positive and --warmups non-negative")
+    if args.orders < 2 or args.orders % 2:
+        parser.error("--orders must be an even number >= 2")
+    if args.interval_ms * 1_000_000 < MIN_INTERVAL_NS:
+        parser.error(f"--interval-ms must be at least {MIN_INTERVAL_NS // 1_000_000}")
+    return args
+
+
+def fast_plan(round_index: int, count: int) -> tuple[bool, ...]:
+    """Alternate fast flags; the first method swaps every round for fairness."""
+    first = round_index % 2 == 1
+    return tuple(first if i % 2 == 0 else not first for i in range(count))
+
+
+def summarize(samples_ns: Sequence[int]) -> dict[str, float]:
+    ms = sorted(sample / 1_000_000 for sample in samples_ns)
+    cuts = statistics.quantiles(ms, n=100, method="inclusive")
+    return {
+        "n": len(ms),
+        "mean": statistics.fmean(ms),
+        "p50": statistics.median(ms),
+        "p90": cuts[89],
+        "p99": cuts[98],
+        "min": ms[0],
+        "max": ms[-1],
+    }
+
+
+def format_table(samples: dict[bool, list[int]]) -> str:
+    columns = ("n", "mean", "p50", "p90", "p99", "min", "max")
+    lines = [f"{'method':<12}" + "".join(f"{name:>10}" for name in columns)]
+    for fast in (False, True):
+        stats = summarize(samples[fast])
+        cells = "".join(
+            f"{stats[name]:>10d}" if name == "n" else f"{stats[name]:>10.2f}"
+            for name in columns
+        )
+        lines.append(f"{f'fast={fast}':<12}" + cells)
+    return "\n".join(lines) + "\n(latency in ms)"
+
+
+def _cancelled(response: CancelOrderResponse) -> bool:
+    return response["status"] == "ok" and response["response"]["data"]["statuses"] == [
+        "success"
+    ]
+
+
+async def _place_round(
+    client: AsyncHyperliquid, count: int, size_decimals: int
+) -> list[int]:
+    px = await client.info.mid_price(COIN) * PRICE_RATIO
+    step = 10**size_decimals
+    sz = math.ceil(NOTIONAL_USDC / px * step) / step
+    order: PlaceOrderRequest = {
+        "coin": COIN,
+        "is_buy": True,
+        "sz": sz,
+        "px": px,
+        "is_market": False,
+        "order_type": limit_order_type(TimeInForce.ALO),
+    }
+    response = await client.place_orders([order.copy() for _ in range(count)])
+    if response["status"] != "ok":
+        raise BenchmarkFailure(f"placement failed: {response['response']}")
+    oids: list[int] = []
+    for status in response["response"]["data"]["statuses"]:
+        resting = status.get("resting") if isinstance(status, dict) else None
+        if not isinstance(resting, dict):
+            raise BenchmarkFailure(f"order did not rest: {status!r}")
+        oids.append(resting["oid"])
+    return oids
+
+
+async def _run(args: argparse.Namespace, credentials: Credentials) -> str:
+    pacer = WeightedPacer(interval_ns=args.interval_ms * 1_000_000)
+    samples: dict[bool, list[int]] = {False: [], True: []}
+    async with AsyncHyperliquid(
+        credentials.master_address,
+        credentials.signing_key,
+        vault_address=credentials.subaccount_address,
+        network=Network.TESTNET,
+    ) as client:
+        await client.info.refresh_metadata()
+        validate_roles(
+            credentials.master_address,
+            await client.info.user_role(credentials.api_wallet_address),
+            await client.info.user_role(credentials.subaccount_address),
+        )
+        size_decimals = await client.info.size_decimals(COIN)
+        pending: list[int] = []
+        try:
+            for round_index in range(args.warmups + args.rounds):
+                await pacer.wait(weight=1)
+                pending = await _place_round(client, args.orders, size_decimals)
+                plan = fast_plan(round_index, len(pending))
+                for oid, fast in zip(tuple(pending), plan, strict=True):
+                    await pacer.wait(weight=1)
+                    start = perf_counter_ns()
+                    response = await client.cancel_order(
+                        CancelOrder(COIN, oid), fast=fast
+                    )
+                    elapsed = perf_counter_ns() - start
+                    if not _cancelled(response):
+                        raise BenchmarkFailure(f"cancel failed: {response!r}")
+                    pending.remove(oid)
+                    if round_index >= args.warmups:
+                        samples[fast].append(elapsed)
+        finally:
+            if pending:
+                await client.cancel_orders(tuple(CancelOrder(COIN, o) for o in pending))
+    return format_table(samples)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    from dotenv import load_dotenv
+
+    load_dotenv(Path(".env.local"), override=False)
+    try:
+        credentials = Credentials.from_environ(os.environ)
+        print(asyncio.run(_run(args, credentials)))
+    except BenchmarkFailure as error:
+        print(f"fast-cancel benchmark failed: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

async_hyperliquid-1.2.0/docs/_static/language-switcher.css

@@ -0,0 +1,14 @@
+.sidebar-language-switch {
+  align-items: center;
+  display: flex;
+  font-size: 0.875rem;
+  gap: 0.5rem;
+  justify-content: center;
+  margin: -0.5rem 0 0.75rem;
+}
+
+.sidebar-language-switch a[aria-current="page"] {
+  color: var(--color-foreground-primary);
+  font-weight: 600;
+  text-decoration: none;
+}

async_hyperliquid-1.2.0/docs/_templates/sidebar/language-switcher.html

@@ -0,0 +1,15 @@
+<nav class="sidebar-language-switch" aria-label="Documentation language">
+  {% if documentation_is_hosted %}
+  <a href="https://async-hyperliquid.readthedocs.io/en/{{ documentation_version|e }}/{{ pagename|e }}.html"
+     lang="en"{% if documentation_language == "en" %} aria-current="page"{% endif %}>English</a>
+  <span aria-hidden="true">|</span>
+  <a href="https://async-hyperliquid.readthedocs.io/zh-cn/{{ documentation_version|e }}/{{ pagename|e }}.html"
+     lang="zh-CN"{% if documentation_language == "zh-cn" %} aria-current="page"{% endif %}>简体中文</a>
+  {% else %}
+  <a href="{{ documentation_root_prefix|e }}en/{{ pagename|e }}.html"
+     lang="en"{% if documentation_language == "en" %} aria-current="page"{% endif %}>English</a>
+  <span aria-hidden="true">|</span>
+  <a href="{{ documentation_root_prefix|e }}zh_CN/{{ pagename|e }}.html"
+     lang="zh-CN"{% if documentation_language == "zh-cn" %} aria-current="page"{% endif %}>简体中文</a>
+  {% endif %}
+</nav>

async_hyperliquid-1.2.0/docs/conf.py

@@ -0,0 +1,94 @@
+import os
+import re
+from importlib.metadata import metadata, version as package_version
+
+
+project = "async-hyperliquid"
+release = package_version(project)
+version = release
+
+requires_python = metadata(project)["Requires-Python"]
+minimum_python = requires_python.removeprefix(">=")
+if minimum_python == requires_python:
+    raise RuntimeError(
+        "documentation expects a minimum-only Requires-Python package constraint"
+    )
+
+rst_prolog = "\n".join(
+    (
+        f".. |minimum-python| replace:: {minimum_python}",
+        f".. |requires-python| replace:: ``{requires_python}``",
+    )
+)
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx_copybutton",
+    "sphinx_inline_tabs",
+]
+
+locale_dirs = ["locale/"]
+gettext_compact = False
+gettext_uuid = True
+
+exclude_patterns = ["_build"]
+html_theme = "furo"
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+_HOSTED_TO_SPHINX_LANGUAGE = {"en": "en", "zh-cn": "zh_CN"}
+_SPHINX_TO_HOSTED_LANGUAGE = {
+    value: key for key, value in _HOSTED_TO_SPHINX_LANGUAGE.items()
+}
+_READTHEDOCS_VERSION = os.environ.get("READTHEDOCS_VERSION", "latest")
+_IS_READTHEDOCS = os.environ.get("READTHEDOCS") == "True"
+if not re.fullmatch(r"[a-z0-9._-]+", _READTHEDOCS_VERSION, flags=re.ASCII):
+    raise RuntimeError(
+        "READTHEDOCS_VERSION must be a non-empty Read the Docs version slug"
+    )
+
+rtd_language = os.environ.get("READTHEDOCS_LANGUAGE")
+if rtd_language is not None:
+    try:
+        language = _HOSTED_TO_SPHINX_LANGUAGE[rtd_language]
+    except KeyError as exc:
+        raise RuntimeError(
+            f"unsupported Read the Docs language: {rtd_language}"
+        ) from exc
+
+html_title = project
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+html_css_files = ["language-switcher.css"]
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/language-switcher.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+        "sidebar/variant-selector.html",
+    ]
+}
+
+
+def _add_documentation_context(app, pagename, templatename, context, doctree):
+    del templatename, doctree
+    rendered_language = app.config.language or "en"
+    try:
+        context["documentation_language"] = _SPHINX_TO_HOSTED_LANGUAGE[
+            rendered_language
+        ]
+    except KeyError as exc:
+        raise RuntimeError(
+            f"unsupported Sphinx documentation language: {rendered_language}"
+        ) from exc
+    context["documentation_version"] = _READTHEDOCS_VERSION
+    context["documentation_is_hosted"] = _IS_READTHEDOCS
+    context["documentation_root_prefix"] = "../" * (pagename.count("/") + 1)
+
+
+def setup(app):
+    app.connect("html-page-context", _add_documentation_context)

async_hyperliquid-1.2.0/docs/howto/index.rst

@@ -0,0 +1,17 @@
+How-to guides
+=============
+
+Choose the guide for the outcome you need, then follow its safety and response
+steps before copying an example:
+
+* :doc:`info-queries` covers credential-free market and account reads.
+* :doc:`markets` explains canonical coin names and metadata-derived IDs.
+* :doc:`orders` covers order placement, triggers, TP/SL, TWAP, modification,
+  cancellation, and closing.
+* :doc:`routing` explains main accounts, API wallets, subaccounts, vaults, and
+  endpoint trust boundaries.
+* :doc:`transfers-administration` covers fund-moving operations with explicit
+  signed-action examples, plus paid, administrative, outcome, and validator
+  actions.
+* :doc:`lifecycle-reconciliation` covers sessions, errors, nonce ownership, and
+  ambiguous signed outcomes.