typed-hyperliquid 1.2.2__tar.gz → 1.2.3__tar.gz

{typed_hyperliquid-1.2.2/src/typed_hyperliquid.egg-info → typed_hyperliquid-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typed-hyperliquid
-Version: 1.2.2
+Version: 1.2.3
 Summary: A fully typed, validated async client for the Hyperliquid API.
 Author-email: Marcel Claramunt <marcel@tribulnation.com>
 License-Expression: MIT

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typed-hyperliquid"
-version = "1.2.2"
+version = "1.2.3"
 authors = [
   {name="Marcel Claramunt", email="marcel@tribulnation.com"}
 ]

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/hyperliquid/__init__.py

@@ -7,7 +7,7 @@ from typed_core.exceptions import (
   ApiError, BadRequest, AuthError, RateLimited, LogicError,
 )
 from typed_core.http import HttpClient
-from .core import HYPERLIQUID_MAINNET, HYPERLIQUID_TESTNET
+from .core import HYPERLIQUID_MAINNET, HYPERLIQUID_TESTNET, PaginationError
 from .core.ws import SocketClient
 from .info import Info
 from .exchange import Exchange

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/hyperliquid/core/__init__.pyi

@@ -1,7 +1,7 @@
 from .ws import SocketClient
 from .util import HYPERLIQUID_MAINNET, HYPERLIQUID_TESTNET, timestamp
 from .validation import TypedDict
-from .exc import Error, ApiError, AuthError, NetworkError, RateLimited, ValidationError, LogicError
+from .exc import Error, ApiError, AuthError, NetworkError, RateLimited, ValidationError, LogicError, PaginationError
 
 __all__ = [
   'SocketClient',
@@ -16,4 +16,5 @@ __all__ = [
   'RateLimited',
   'ValidationError',
   'LogicError',
+  'PaginationError',
 ]

typed_hyperliquid-1.2.3/src/hyperliquid/core/exc.py

@@ -0,0 +1,15 @@
+from typed_core import Error, ApiError, AuthError, NetworkError, RateLimited, ValidationError, LogicError
+
+class PaginationError(Error):
+  """A paginated sweep could not continue without silently losing entries.
+
+  Raised by the `*_paged` info helpers when the upstream endpoint cannot be
+  walked safely: either the order of entries sharing a millisecond changed
+  between requests, or a single millisecond holds a whole page of entries, in
+  which case the endpoint has no way to express the rest of that millisecond.
+
+  Stopping is deliberate. The alternative is to skip past the millisecond, which
+  drops entries with no error and no gap indicator.
+  """
+  def __str__(self):
+    return super().__str__()

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/hyperliquid/info/methods/user_fills_by_time.py

@@ -2,6 +2,10 @@ from typing_extensions import Literal, NotRequired, AsyncIterable
 from hyperliquid.core import TypedDict
 import pydantic
 from hyperliquid.info.core import InfoMixin
+from hyperliquid.info.pagination import paginate
+
+PAGE_SIZE = 2000
+"""Maximum number of fills `user_fills_by_time` returns per call."""
 
 class UserFill(TypedDict):
   coin: str
@@ -75,18 +79,28 @@ class UserFillsByTime(InfoMixin):
     A single call to `user_fills_by_time` returns at most 2000 fills, so prefer this
     whenever the requested range may hold more.
 
+    Many fills share a millisecond, so pages are advanced to the last timestamp seen
+    rather than past it, and the re-fetched entries are dropped by position. `tid` is
+    not used as a key: every `Spot Dust Conversion` fill carries the sentinel `tid: 0`.
+
     Args:
       user: Account address.
       start_time: Start time in milliseconds, inclusive.
       end_time: End time in milliseconds, inclusive.
       aggregate_by_time: Aggregate partial fills in the same block.
 
+    Raises:
+      PaginationError: The range cannot be walked without losing fills.
+
     References:
       - [Hyperliquid API docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-a-users-fills-by-time)
     """
-    while end_time is None or start_time < end_time:
-      fills = await self.user_fills_by_time(user, start_time, end_time=end_time, aggregate_by_time=aggregate_by_time)
-      if not fills:
-        break
-      yield fills
-      start_time = max(entry['time'] for entry in fills) + 1
+    async def fetch(cursor: int) -> list[UserFill]:
+      """Fetch one page of fills starting at `cursor`."""
+      return await self.user_fills_by_time(
+        user, cursor, end_time=end_time, aggregate_by_time=aggregate_by_time,
+      )
+    async for page in paginate(
+      fetch, start_time=start_time, end_time=end_time, page_size=PAGE_SIZE,
+    ):
+      yield page

typed_hyperliquid-1.2.3/src/hyperliquid/info/pagination.py

@@ -0,0 +1,94 @@
+"""Time-cursor pagination shared by the `*_paged` info helpers.
+
+Hyperliquid's time-ranged info endpoints return the *oldest* entries of
+`[start_time, end_time]`, capped at a per-endpoint page size, so walking a long
+range means re-issuing the request with the cursor moved forward.
+
+Timestamps are milliseconds and are not unique: a single millisecond routinely
+holds dozens of entries. Moving the cursor to `last_time + 1` therefore drops
+every entry that shares the last millisecond of a truncated page, silently and
+permanently. The cursor is instead moved to `last_time`, which re-fetches that
+millisecond in full, and the already-yielded prefix is removed.
+
+The overlap is removed *by position*, not by an id or a content hash, because
+neither is trustworthy:
+
+- `tid` is not unique for fills. Every `Spot Dust Conversion` fill carries the
+  sentinel `tid: 0`, so keying on it collapses unrelated fills.
+- Funding entries carry no id at all, and for ledger updates `(time, hash)` is
+  explicitly not a primary key: one transaction can emit several deltas.
+- Content hashing would additionally collapse records that are legitimately
+  identical, which nothing in the payloads rules out.
+
+Position is safe because the endpoints return entries in ascending time order,
+`start_time` is inclusive, and the relative order of entries sharing a
+millisecond is stable across requests. The entries already yielded for the
+cursor millisecond are therefore exactly the prefix of the next response, and
+that prefix is verified on every page rather than assumed.
+
+Callers must pass the endpoint's real page cap as `page_size`. It is the signal
+that separates "this page is short because the range is exhausted" from "this
+page is short because it was cut", and declaring it larger than the true cap
+would reintroduce silent loss.
+"""
+from typing_extensions import Any, AsyncIterable, Awaitable, Callable, Mapping, TypeVar
+from hyperliquid.core import PaginationError
+
+Entry = TypeVar('Entry', bound=Mapping[str, Any])
+
+async def paginate(
+  fetch: Callable[[int], Awaitable[list[Entry]]], *,
+  start_time: int, end_time: int | None, page_size: int,
+) -> AsyncIterable[list[Entry]]:
+  """Walk a time-ranged Hyperliquid endpoint, yielding every entry exactly once.
+
+  Args:
+    fetch: Fetch one page starting at the given timestamp, inclusive. It must
+      apply the same `end_time` on every call.
+    start_time: Start time in milliseconds, inclusive.
+    end_time: End time in milliseconds, inclusive.
+    page_size: Maximum number of entries the endpoint returns per call.
+
+  Raises:
+    PaginationError: The upstream order of entries sharing a millisecond changed
+      mid-sweep, or a single millisecond fills a whole page, so the rest of that
+      millisecond is unreachable and continuing would drop it.
+
+  References:
+    - [Hyperliquid API docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint)
+  """
+  cursor = start_time
+  overlap: list[Entry] = []
+  while end_time is None or cursor <= end_time:
+    page = await fetch(cursor)
+    if not page:
+      return
+    if page[:len(overlap)] != overlap:
+      raise PaginationError(
+        f'Hyperliquid returned different entries for timestamp {cursor} than it '
+        'did on the previous page. Pagination relies on the order of entries '
+        'sharing a timestamp being stable across requests; it was not, so the '
+        'sweep stopped instead of dropping or duplicating entries.'
+      )
+    fresh = page[len(overlap):]
+    if fresh:
+      yield fresh
+    last_time = max(entry['time'] for entry in page)
+    if last_time > cursor:
+      cursor = last_time
+      overlap = [entry for entry in page if entry['time'] == last_time]
+    elif len(page) >= page_size:
+      # Every entry of a full page shares `cursor`, so the page was truncated
+      # inside that millisecond. The endpoint pages by time only, so the rest of
+      # it is unreachable and moving on would drop it.
+      raise PaginationError(
+        f'Timestamp {cursor} holds at least {len(page)} entries, filling a whole '
+        'page. Hyperliquid pages by time only, so the rest of that millisecond '
+        'cannot be requested, and the sweep stopped instead of skipping it. '
+        f'Resume from {cursor + 1} to continue while accepting that loss.'
+      )
+    else:
+      # A page shorter than `page_size` was not truncated, so every entry at
+      # `cursor` is already yielded and the millisecond can be stepped over.
+      cursor += 1
+      overlap = []

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/hyperliquid/info/perps/funding_history.py

@@ -2,6 +2,10 @@ from typing_extensions import AsyncIterable
 from hyperliquid.core import TypedDict
 import pydantic
 from hyperliquid.info.core import InfoMixin
+from hyperliquid.info.pagination import paginate
+
+PAGE_SIZE = 500
+"""Maximum number of entries `funding_history` returns per call."""
 
 class FundingHistoryEntry(TypedDict):
   coin: str
@@ -44,17 +48,25 @@ class FundingHistory(InfoMixin):
     A single call to `funding_history` returns at most 500 entries, so prefer this
     whenever the requested range may hold more.
 
+    Pages are advanced to the last timestamp seen rather than past it, and the
+    re-fetched entries are dropped by position, so entries sharing a millisecond
+    are never skipped at a page boundary.
+
     Args:
       coin: Coin, e.g. "ETH".
       start_time: Start time in milliseconds, inclusive.
       end_time: End time in milliseconds, inclusive.
 
+    Raises:
+      PaginationError: The range cannot be walked without losing entries.
+
     References:
       - [Hyperliquid API docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-historical-funding-rates)
     """
-    while end_time is None or start_time < end_time:
-      fundings = await self.funding_history(coin, start_time, end_time=end_time)
-      if not fundings:
-        break
-      yield fundings
-      start_time = max(entry['time'] for entry in fundings) + 1
+    async def fetch(cursor: int) -> list[FundingHistoryEntry]:
+      """Fetch one page of funding rates starting at `cursor`."""
+      return await self.funding_history(coin, cursor, end_time=end_time)
+    async for page in paginate(
+      fetch, start_time=start_time, end_time=end_time, page_size=PAGE_SIZE,
+    ):
+      yield page

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/hyperliquid/info/perps/user_funding.py

@@ -2,6 +2,10 @@ from typing_extensions import AsyncIterable, Literal
 from hyperliquid.core import TypedDict
 import pydantic
 from hyperliquid.info.core import InfoMixin
+from hyperliquid.info.pagination import paginate
+
+PAGE_SIZE = 500
+"""Maximum number of entries `user_funding` returns per call."""
 
 class FundingDelta(TypedDict):
   type: Literal['funding']
@@ -54,14 +58,28 @@ class UserFunding(InfoMixin):
     A single call to `user_funding` returns at most 500 entries, so prefer this
     whenever the requested range may hold more.
 
+    Every open position is funded on the same millisecond, so pages are advanced to
+    the last timestamp seen rather than past it, and the re-fetched entries are
+    dropped by position. Funding entries carry no unique id, so no key-based
+    deduplication is possible.
+
     Args:
       user: Account address.
       start_time: Start time in milliseconds, inclusive.
       end_time: End time in milliseconds, inclusive.
+
+    Raises:
+      PaginationError: The range cannot be walked without losing entries. Notably,
+        an account holding 500 or more funded positions cannot be swept at all,
+        since one funding millisecond then fills a whole page.
+
+    References:
+      - [Hyperliquid API docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-a-users-funding-history-or-non-funding-ledger-updates)
     """
-    while end_time is None or start_time < end_time:
-      fundings = await self.user_funding(user, start_time, end_time=end_time)
-      if not fundings:
-        break
-      yield fundings
-      start_time = max(entry['time'] for entry in fundings) + 1
+    async def fetch(cursor: int) -> list[UserFundingEntry]:
+      """Fetch one page of funding entries starting at `cursor`."""
+      return await self.user_funding(user, cursor, end_time=end_time)
+    async for page in paginate(
+      fetch, start_time=start_time, end_time=end_time, page_size=PAGE_SIZE,
+    ):
+      yield page

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/hyperliquid/info/perps/user_non_funding_ledger_updates.py

@@ -4,6 +4,10 @@ from decimal import Decimal
 from hyperliquid.core import TypedDict
 import pydantic
 from hyperliquid.info.core import InfoMixin
+from hyperliquid.info.pagination import paginate
+
+PAGE_SIZE = 2000
+"""Maximum number of entries `user_non_funding_ledger_updates` returns per call."""
 
 class DepositDelta(TypedDict):
   """Funds deposited into the account."""
@@ -317,17 +321,26 @@ class UserNonFundingLedgerUpdates(InfoMixin):
     the rest, so any account with more history is truncated without an error. Prefer this
     over `user_non_funding_ledger_updates` whenever complete history matters.
 
+    One transaction can emit several deltas on the same millisecond, so pages are
+    advanced to the last timestamp seen rather than past it, and the re-fetched
+    entries are dropped by position. `(time, hash)` is not used as a key because it
+    is not unique, and hashing the body would collapse identical deltas.
+
     Args:
       user: Account address.
       start_time: Start time in milliseconds, inclusive.
       end_time: End time in milliseconds, inclusive.
 
+    Raises:
+      PaginationError: The range cannot be walked without losing entries.
+
     References:
       - [Hyperliquid API docs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-a-users-funding-history-or-non-funding-ledger-updates)
     """
-    while end_time is None or start_time < end_time:
-      updates = await self.user_non_funding_ledger_updates(user, start_time, end_time=end_time)
-      if not updates:
-        break
-      yield updates
-      start_time = max(entry['time'] for entry in updates) + 1
+    async def fetch(cursor: int) -> UserNonFundingLedgerUpdatesResponse:
+      """Fetch one page of ledger updates starting at `cursor`."""
+      return await self.user_non_funding_ledger_updates(user, cursor, end_time=end_time)
+    async for page in paginate(
+      fetch, start_time=start_time, end_time=end_time, page_size=PAGE_SIZE,
+    ):
+      yield page

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3/src/typed_hyperliquid.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typed-hyperliquid
-Version: 1.2.2
+Version: 1.2.3
 Summary: A fully typed, validated async client for the Hyperliquid API.
 Author-email: Marcel Claramunt <marcel@tribulnation.com>
 License-Expression: MIT

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.3}/src/typed_hyperliquid.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ src/hyperliquid/exchange/core/mixin.py
 src/hyperliquid/exchange/core/signing.py
 src/hyperliquid/info/__init__.py
 src/hyperliquid/info/core.py
+src/hyperliquid/info/pagination.py
 src/hyperliquid/info/methods/__init__.py
 src/hyperliquid/info/methods/aligned_quote_token_info.py
 src/hyperliquid/info/methods/all_borrow_lend_reserve_states.py

typed_hyperliquid-1.2.2/src/hyperliquid/core/exc.py

@@ -1 +0,0 @@
-from typed_core import Error, ApiError, AuthError, NetworkError, RateLimited, ValidationError, LogicError