async-hyperliquid 1.1.0__tar.gz → 1.2.0__tar.gz

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/CHANGELOG.md

@@ -5,6 +5,17 @@ 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

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: async-hyperliquid
-Version: 1.1.0
+Version: 1.2.0
 Summary: Async Hyperliquid client using aiohttp
 Keywords: dex,hyperliquid,async,aiohttp,trading,cryptocurrency,defi
 Author: Yuki
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 
 [![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.1.0)](https://pypi.org/project/async-hyperliquid/)
+[![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

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/README.md

@@ -2,7 +2,7 @@
 
 [![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.1.0)](https://pypi.org/project/async-hyperliquid/)
+[![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

{async_hyperliquid-1.1.0 → 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

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.1.0 → async_hyperliquid-1.2.0}/docs/howto/orders.rst

@@ -406,6 +406,11 @@ Use ``CancelOrder(coin, oid)`` with ``cancel_order()`` or ``cancel_orders()``.
 Use ``CancelByCloid(coin, cloid)`` with ``cancel_by_cloid()`` or
 ``cancel_orders_by_cloid()``. Empty batches are rejected locally.
 
+All four cancel methods accept ``fast=True``, which sends Hyperliquid's ``f``
+flag. The exchange rejects fast cancels that target trigger orders, and a future
+network upgrade will prioritize fast cancels in the mempool. With the default
+``fast=False`` the flag is omitted from the signed action.
+
 ``ModifyOrderRequest`` identifies the order by integer order ID or ``Cloid`` and
 contains the complete replacement order. ``modify_order()`` returns a default
 acknowledgement; ``modify_orders()`` returns per-order statuses.

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/docs/locale/zh_CN/LC_MESSAGES/howto/orders.po

@@ -288,6 +288,18 @@ msgstr ""
 "搭配使用。将 ``CancelByCloid(coin, cloid)`` 与 ``cancel_by_cloid()`` 或 "
 "``cancel_orders_by_cloid()`` 搭配使用。空批次会在本地被拒绝。"
 
+#: ../../howto/orders.rst:409
+msgid ""
+"All four cancel methods accept ``fast=True``, which sends Hyperliquid's "
+"``f`` flag. The exchange rejects fast cancels that target trigger orders,"
+" and a future network upgrade will prioritize fast cancels in the "
+"mempool. With the default ``fast=False`` the flag is omitted from the "
+"signed action."
+msgstr ""
+"四个撤单方法都接受 ``fast=True``，用于发送 Hyperliquid 的 ``f`` 标志。"
+"交易所会拒绝针对触发单（trigger order）的快速撤单；未来的网络升级会在 mempool "
+"中优先处理快速撤单。默认 ``fast=False`` 时，签名的 action 中不包含该标志。"
+
 #: ../../howto/orders.rst:409 2815403bb6ba4974a7f7a2680ee41f54
 msgid ""
 "``ModifyOrderRequest`` identifies the order by integer order ID or "

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "async-hyperliquid"
-version = "1.1.0"
+version = "1.2.0"
 requires-python = ">=3.12"
 description = "Async Hyperliquid client using aiohttp"
 authors = [{ name = "Yuki", email = "yuqi.lyle@gmail.com" }]

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/src/async_hyperliquid/client.py

@@ -332,12 +332,22 @@ class AsyncHyperliquid:
         )
 
     async def cancel_order(
-        self, order: CancelOrder, *, expires_after: int | None = None
+        self,
+        order: CancelOrder,
+        *,
+        fast: bool = False,
+        expires_after: int | None = None,
     ) -> CancelOrderResponse:
-        return await self.cancel_orders((order,), expires_after=expires_after)
+        return await self.cancel_orders(
+            (order,), fast=fast, expires_after=expires_after
+        )
 
     async def cancel_orders(
-        self, orders: Sequence[CancelOrder], *, expires_after: int | None = None
+        self,
+        orders: Sequence[CancelOrder],
+        *,
+        fast: bool = False,
+        expires_after: int | None = None,
     ) -> CancelOrderResponse:
         commands = tuple(orders)
         if not commands:
@@ -350,16 +360,26 @@ class AsyncHyperliquid:
             for order, market in zip(commands, markets, strict=True)
         )
         return await self._exchange._submit_cancels(
-            cancels, expires_after=expires_after
+            cancels, fast=fast, expires_after=expires_after
         )
 
     async def cancel_by_cloid(
-        self, order: CancelByCloid, *, expires_after: int | None = None
+        self,
+        order: CancelByCloid,
+        *,
+        fast: bool = False,
+        expires_after: int | None = None,
     ) -> CancelOrderResponse:
-        return await self.cancel_orders_by_cloid((order,), expires_after=expires_after)
+        return await self.cancel_orders_by_cloid(
+            (order,), fast=fast, expires_after=expires_after
+        )
 
     async def cancel_orders_by_cloid(
-        self, orders: Sequence[CancelByCloid], *, expires_after: int | None = None
+        self,
+        orders: Sequence[CancelByCloid],
+        *,
+        fast: bool = False,
+        expires_after: int | None = None,
     ) -> CancelOrderResponse:
         commands = tuple(orders)
         if not commands:
@@ -372,7 +392,7 @@ class AsyncHyperliquid:
             for order, market in zip(commands, markets, strict=True)
         )
         return await self._exchange._submit_cloid_cancels(
-            cancels, expires_after=expires_after
+            cancels, fast=fast, expires_after=expires_after
         )
 
     @staticmethod

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/src/async_hyperliquid/exchange.py

@@ -195,24 +195,34 @@ class ExchangeClient:
         return await self._submit_action(action, "order", expires_after=expires_after)
 
     async def _submit_cancels(
-        self, cancels: Sequence[EncodedCancel], *, expires_after: int | None = None
+        self,
+        cancels: Sequence[EncodedCancel],
+        *,
+        fast: bool = False,
+        expires_after: int | None = None,
     ) -> CancelOrderResponse:
         encoded = list(cancels)
         if not encoded:
             raise ValueError("orders must not be empty")
         action = CancelAction(type="cancel", cancels=encoded)
+        if fast:
+            # Hyperliquid rejects actions hashed with f=false, so only send f=true.
+            action["f"] = True
         return await self._submit_action(action, "cancel", expires_after=expires_after)
 
     async def _submit_cloid_cancels(
         self,
         cancels: Sequence[EncodedCancelByCloid],
         *,
+        fast: bool = False,
         expires_after: int | None = None,
     ) -> CancelOrderResponse:
         encoded = list(cancels)
         if not encoded:
             raise ValueError("orders must not be empty")
         action = CancelByCloidAction(type="cancelByCloid", cancels=encoded)
+        if fast:
+            action["f"] = True
         return await self._submit_action(action, "cancel", expires_after=expires_after)
 
     async def _post_envelope(

{async_hyperliquid-1.1.0 → async_hyperliquid-1.2.0}/src/async_hyperliquid/types/exchange.py

@@ -144,6 +144,7 @@ class EncodedCancel(TypedDict):
 class CancelAction(TypedDict):
     type: Literal["cancel"]
     cancels: list[EncodedCancel]
+    f: NotRequired[Literal[True]]
 
 
 class EncodedCancelByCloid(TypedDict):
@@ -154,6 +155,7 @@ class EncodedCancelByCloid(TypedDict):
 class CancelByCloidAction(TypedDict):
     type: Literal["cancelByCloid"]
     cancels: list[EncodedCancelByCloid]
+    f: NotRequired[Literal[True]]
 
 
 class EncodedModify(TypedDict):