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

{typed_hyperliquid-1.2.2 → typed_hyperliquid-1.2.4}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Marcel Claramunt
+Copyright (c) 2026 Tribulnation Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typed-hyperliquid
-Version: 1.2.2
+Version: 1.2.4
 Summary: A fully typed, validated async client for the Hyperliquid API.
 Author-email: Marcel Claramunt <marcel@tribulnation.com>
 License-Expression: MIT
@@ -15,12 +15,13 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typed-core>=0.2.0
+Requires-Dist: lazy-loader
 Requires-Dist: eth-account
 Requires-Dist: msgpack
 Dynamic: license-file
 
 <p align="center">
-  <a href="https://hyperliquid.tribulnation.com">
+  <a href="https://tribulnation.com/typed/hyperliquid">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tribulnation/hyperliquid/refs/heads/main/media/hyperliquid-dark.svg">
       <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tribulnation/hyperliquid/refs/heads/main/media/hyperliquid-light.svg">
@@ -40,7 +41,7 @@ Dynamic: license-file
   <a href="https://pypi.org/project/typed-hyperliquid/">
     <img src="https://img.shields.io/pypi/pyversions/typed-hyperliquid.svg" alt="Python versions">
   </a>
-  <a href="https://hyperliquid.tribulnation.com/">
+  <a href="https://tribulnation.com/typed/hyperliquid/">
     <img src="https://img.shields.io/badge/docs-live-black" alt="Docs">
   </a>
   <a href="LICENSE">
@@ -50,7 +51,7 @@ Dynamic: license-file
 
 ---
 
-- **Documentation**: [https://hyperliquid.tribulnation.com](https://hyperliquid.tribulnation.com)
+- **Documentation**: [https://tribulnation.com/typed/hyperliquid](https://tribulnation.com/typed/hyperliquid)
 - **Source Code**: [https://github.com/tribulnation/hyperliquid](https://github.com/tribulnation/hyperliquid)
 
 ---
@@ -67,11 +68,12 @@ async with Hyperliquid.ws(public=True) as client:
 
 ## Why Typed Hyperliquid?
 
-- **🎯 Precise Types**: Typed endpoint inputs and responses.
-- **✅ Runtime Validation**: Validated responses by default.
-- **⚡ Async First**: HTTP, WebSocket RPC, and subscriptions.
-- **📚 Full API Surface**: `client.info`, `client.exchange`, and
-  `client.streams`.
+- **🎯 Precise Types**: Typed endpoint inputs and responses, not `dict`/`Any`.
+- **✅ Runtime Validation**: Responses validated by default, not just typed on paper.
+- **⚡ Async First**: HTTP, request-response WebSocket, and subscription streams, built for
+  concurrent workflows.
+- **📚 Full Surface**: `client.info`, `client.exchange`, and `client.streams` -- perps,
+  spot, and every documented info/exchange/stream endpoint, not just the popular ones.
 
 ## Installation
 
@@ -81,16 +83,17 @@ pip install typed-hyperliquid
 
 ## How To
 
-- [Place & Manage Orders](https://hyperliquid.tribulnation.com/how-to/place-and-manage-orders/)
-- [Fetch Market Data](https://hyperliquid.tribulnation.com/how-to/fetch-market-data/)
-- [Fetch Your Balances & Positions](https://hyperliquid.tribulnation.com/how-to/fetch-balances-and-positions/)
-- [Fetch Your Transactions](https://hyperliquid.tribulnation.com/how-to/fetch-transactions/)
-- [Listen To Your Trades](https://hyperliquid.tribulnation.com/how-to/listen-to-your-trades/)
-- [Listen To Public Data](https://hyperliquid.tribulnation.com/how-to/listen-to-public-data/)
+- [Place & Manage Orders](https://tribulnation.com/typed/hyperliquid/how-to/place-and-manage-orders)
+- [Fetch Market Data](https://tribulnation.com/typed/hyperliquid/how-to/fetch-market-data)
+- [Fetch Your Balances & Positions](https://tribulnation.com/typed/hyperliquid/how-to/fetch-balances-and-positions)
+- [Fetch Your Transactions](https://tribulnation.com/typed/hyperliquid/how-to/fetch-transactions)
+- [Listen To Your Trades](https://tribulnation.com/typed/hyperliquid/how-to/listen-to-your-trades)
+- [Listen To Public Data](https://tribulnation.com/typed/hyperliquid/how-to/listen-to-public-data)
 
 ## Reference
 
-- [Authenticated Setup](https://hyperliquid.tribulnation.com/authenticated-setup/)
-- [Error Handling](https://hyperliquid.tribulnation.com/reference/error-handling/)
-- [Environment Variables](https://hyperliquid.tribulnation.com/reference/env-vars/)
-- [Generated API Reference](https://hyperliquid.tribulnation.com/reference/api/)
+- [Authenticated Setup](https://tribulnation.com/typed/hyperliquid/authenticated-setup)
+- [Async Usage](https://tribulnation.com/typed/hyperliquid/reference/async-usage)
+- [Error Handling](https://tribulnation.com/typed/hyperliquid/reference/error-handling)
+- [Environment Variables](https://tribulnation.com/typed/hyperliquid/reference/env-vars)
+- [Timestamps](https://tribulnation.com/typed/hyperliquid/reference/timestamps)

typed_hyperliquid-1.2.4/README.md

@@ -0,0 +1,77 @@
+<p align="center">
+  <a href="https://tribulnation.com/typed/hyperliquid">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tribulnation/hyperliquid/refs/heads/main/media/hyperliquid-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tribulnation/hyperliquid/refs/heads/main/media/hyperliquid-light.svg">
+      <img alt="Typed Hyperliquid" src="https://raw.githubusercontent.com/tribulnation/hyperliquid/refs/heads/main/media/hyperliquid-light.svg" width="520">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <em>A fully typed, validated async client for the Hyperliquid API.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/typed-hyperliquid/">
+    <img src="https://img.shields.io/pypi/v/typed-hyperliquid.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/typed-hyperliquid/">
+    <img src="https://img.shields.io/pypi/pyversions/typed-hyperliquid.svg" alt="Python versions">
+  </a>
+  <a href="https://tribulnation.com/typed/hyperliquid/">
+    <img src="https://img.shields.io/badge/docs-live-black" alt="Docs">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/pypi/l/typed-hyperliquid.svg" alt="License">
+  </a>
+</p>
+
+---
+
+- **Documentation**: [https://tribulnation.com/typed/hyperliquid](https://tribulnation.com/typed/hyperliquid)
+- **Source Code**: [https://github.com/tribulnation/hyperliquid](https://github.com/tribulnation/hyperliquid)
+
+---
+
+```python
+from hyperliquid import Hyperliquid
+
+async with Hyperliquid.ws(public=True) as client:
+  stream = await client.streams.trades('BTC')
+  async for msg in stream:
+    for trade in msg:
+      print(trade['px'], trade['sz'], trade['side'])
+```
+
+## Why Typed Hyperliquid?
+
+- **🎯 Precise Types**: Typed endpoint inputs and responses, not `dict`/`Any`.
+- **✅ Runtime Validation**: Responses validated by default, not just typed on paper.
+- **⚡ Async First**: HTTP, request-response WebSocket, and subscription streams, built for
+  concurrent workflows.
+- **📚 Full Surface**: `client.info`, `client.exchange`, and `client.streams` -- perps,
+  spot, and every documented info/exchange/stream endpoint, not just the popular ones.
+
+## Installation
+
+```bash
+pip install typed-hyperliquid
+```
+
+## How To
+
+- [Place & Manage Orders](https://tribulnation.com/typed/hyperliquid/how-to/place-and-manage-orders)
+- [Fetch Market Data](https://tribulnation.com/typed/hyperliquid/how-to/fetch-market-data)
+- [Fetch Your Balances & Positions](https://tribulnation.com/typed/hyperliquid/how-to/fetch-balances-and-positions)
+- [Fetch Your Transactions](https://tribulnation.com/typed/hyperliquid/how-to/fetch-transactions)
+- [Listen To Your Trades](https://tribulnation.com/typed/hyperliquid/how-to/listen-to-your-trades)
+- [Listen To Public Data](https://tribulnation.com/typed/hyperliquid/how-to/listen-to-public-data)
+
+## Reference
+
+- [Authenticated Setup](https://tribulnation.com/typed/hyperliquid/authenticated-setup)
+- [Async Usage](https://tribulnation.com/typed/hyperliquid/reference/async-usage)
+- [Error Handling](https://tribulnation.com/typed/hyperliquid/reference/error-handling)
+- [Environment Variables](https://tribulnation.com/typed/hyperliquid/reference/env-vars)
+- [Timestamps](https://tribulnation.com/typed/hyperliquid/reference/timestamps)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typed-hyperliquid"
-version = "1.2.2"
+version = "1.2.4"
 authors = [
   {name="Marcel Claramunt", email="marcel@tribulnation.com"}
 ]
@@ -19,6 +19,7 @@ classifiers = [
 ]
 dependencies = [
   "typed-core>=0.2.0",
+  "lazy-loader",
   "eth-account",
   "msgpack"
 ]
@@ -31,4 +32,4 @@ Documentation = "https://hyperliquid.tribulnation.com"
 Website = "https://tribulnation.com"
 
 [tool.setuptools.package-data]
-hyperliquid = ["py.typed"]
+hyperliquid = ["py.typed", "*.pyi", "**/*.pyi"]

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

@@ -3,11 +3,17 @@ import asyncio as _asyncio
 from eth_account.account import Account as _Account
 from eth_account.signers.local import LocalAccount
 from typed_core.exceptions import (
-  Error, NetworkError, ValidationError,
-  ApiError, BadRequest, AuthError, RateLimited, LogicError,
+  Error,
+  NetworkError,
+  ValidationError,
+  ApiError,
+  BadRequest,
+  AuthError,
+  RateLimited,
+  LogicError,
 )
 from typed_core.http import HttpClient
-from .core import HYPERLIQUID_MAINNET, HYPERLIQUID_TESTNET
+from .core import ws_url as _resolve_ws_url
 from .core.ws import SocketClient
 from .info import Info
 from .exchange import Exchange
@@ -15,14 +21,19 @@ from .streams import Streams
 
 Wallet = LocalAccount | str | bytes | int
 
+
 def _env_wallet(mainnet: bool = True) -> LocalAccount | None:
   """Load the network-specific wallet from the environment."""
   import os
+
   key = 'HYPERLIQUID_PRIVATE_KEY' if mainnet else 'HYPERLIQUID_TESTNET_PRIVATE_KEY'
   if (pk := os.getenv(key)) is not None:
     return _Account.from_key(pk)
 
-def _parse_wallet(wallet: Wallet | None, *, mainnet: bool = True) -> LocalAccount | None:
+
+def _parse_wallet(
+  wallet: Wallet | None, *, mainnet: bool = True
+) -> LocalAccount | None:
   """Parse an explicit wallet or load the network-specific environment wallet."""
   if wallet is None:
     return _env_wallet(mainnet=mainnet)
@@ -31,9 +42,11 @@ def _parse_wallet(wallet: Wallet | None, *, mainnet: bool = True) -> LocalAccoun
   else:
     return _Account.from_key(wallet)
 
+
 @_dataclass
 class Hyperliquid:
   """Composite Hyperliquid client for info, streams, and exchange APIs."""
+
   info: Info
   streams: Streams
   _exchange: Exchange | None = _field(default=None, repr=False)
@@ -51,9 +64,14 @@ class Hyperliquid:
 
   @classmethod
   def http(
-    cls, wallet: Wallet | None = None, /, *,
-    mainnet: bool = True, validate: bool = True,
-    public: bool = False, base_url: str | None = None,
+    cls,
+    wallet: Wallet | None = None,
+    /,
+    *,
+    mainnet: bool = True,
+    validate: bool = True,
+    public: bool = False,
+    base_url: str | None = None,
     ws_url: str | None = None,
   ):
     """Create a new Hyperliquid client with HTTP transport.
@@ -81,12 +99,18 @@ class Hyperliquid:
       exchange = None
     else:
       exchange = Exchange.http(
-        wallet, mainnet=mainnet, validate=validate, http=http,
+        wallet,
+        mainnet=mainnet,
+        validate=validate,
+        http=http,
         base_url=base_url,
       )
     return cls(
       info=Info.http(
-        mainnet=mainnet, validate=validate, http=http, base_url=base_url,
+        mainnet=mainnet,
+        validate=validate,
+        http=http,
+        base_url=base_url,
       ),
       streams=Streams.new(mainnet=mainnet, validate=validate, ws_url=ws_url),
       _exchange=exchange,
@@ -94,8 +118,13 @@ class Hyperliquid:
 
   @classmethod
   def ws(
-    cls, wallet: Wallet | None = None, *, mainnet: bool = True,
-    validate: bool = True, public: bool = False, ws_url: str | None = None,
+    cls,
+    wallet: Wallet | None = None,
+    *,
+    mainnet: bool = True,
+    validate: bool = True,
+    public: bool = False,
+    ws_url: str | None = None,
   ):
     """Create a new Hyperliquid client with WebSocket transport.
 
@@ -109,8 +138,7 @@ class Hyperliquid:
       ws_url: Custom WebSocket URL. If provided, takes precedence over
         `mainnet`.
     """
-    domain = HYPERLIQUID_MAINNET if mainnet else HYPERLIQUID_TESTNET
-    ws = SocketClient(url=ws_url or f'wss://{domain}/ws')
+    ws = SocketClient(url=ws_url or _resolve_ws_url(mainnet))
     wallet = _parse_wallet(wallet, mainnet=mainnet)
     if wallet is None:
       if not public:
@@ -121,7 +149,10 @@ class Hyperliquid:
       exchange = None
     else:
       exchange = Exchange.ws_of(
-        wallet, ws=ws, mainnet=mainnet, validate=validate,
+        wallet,
+        ws=ws,
+        mainnet=mainnet,
+        validate=validate,
       )
     return cls(
       info=Info.ws_of(ws, validate=validate),
@@ -129,7 +160,6 @@ class Hyperliquid:
       _exchange=exchange,
     )
 
-
   async def __aenter__(self):
     enters = [
       self.info.__aenter__(),

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

@@ -1,2 +1,3 @@
 import lazy_loader as lazy
-__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

typed_hyperliquid-1.2.4/src/hyperliquid/core/__init__.pyi

@@ -0,0 +1,31 @@
+from .ws import SocketClient
+from .urls import HYPERLIQUID_MAINNET, HYPERLIQUID_TESTNET, http_base_url, ws_url
+from .types import timestamp, Timestamp
+from .exc import (
+  Error,
+  ApiError,
+  AuthError,
+  NetworkError,
+  RateLimited,
+  ValidationError,
+  BadRequest,
+  LogicError,
+)
+
+__all__ = [
+  'SocketClient',
+  'HYPERLIQUID_MAINNET',
+  'HYPERLIQUID_TESTNET',
+  'http_base_url',
+  'ws_url',
+  'timestamp',
+  'Timestamp',
+  'Error',
+  'ApiError',
+  'AuthError',
+  'NetworkError',
+  'RateLimited',
+  'ValidationError',
+  'BadRequest',
+  'LogicError',
+]

typed_hyperliquid-1.2.4/src/hyperliquid/core/endpoint/rpc.py

@@ -0,0 +1,51 @@
+"""Base endpoint class for RPC endpoints -- shared by `info` and `exchange`, the two
+surfaces reachable over either HTTP or the shared WebSocket connection, both with the
+same request/reply shape: one JSON payload in, one decoded value out.
+
+No `method`/`path` decomposition here: Hyperliquid has exactly one URL per surface
+(`/info`, `/exchange`) and selects the operation via a `type` field inside the payload,
+not the URL. No `authed_request` split either -- `exchange`'s "authentication" is a
+signature embedded in the payload itself (see `exchange/core/auth.py`), built one layer
+above this class, not a header a transport attaches generically.
+
+Not frozen, unlike the generic template: every leaf endpoint method (`info.l2_book`,
+`exchange.order`, ...) is its own single-method mixin, and `Info`/`Exchange`/`Streams`
+compose ~20-100 of them via multiple inheritance into one flat, `type`-discriminated
+namespace matching the venue's own flat request shape -- not nested `cached_property`
+subsections. Python's `dataclasses` requires every class in an inheritance chain to
+agree on frozen-ness, so freezing this base would force freezing that entire composed
+chain for no behavioral benefit (nothing here is ever mutated post-construction).
+"""
+
+from typing_extensions import Any, Mapping, Protocol, Self
+from dataclasses import dataclass
+
+
+class RpcClient(Protocol):
+  """Structural interface a transport implements to back an `RpcEndpoint`."""
+
+  async def request(self, payload: Mapping[str, Any]) -> Any:
+    """Send one request payload and return the decoded response value."""
+    ...
+
+  async def __aenter__(self) -> Self: ...
+
+  async def __aexit__(self, exc_type, exc_value, traceback): ...
+
+
+@dataclass(kw_only=True)
+class RpcEndpoint:
+  """Base class for RPC endpoints."""
+
+  client: RpcClient
+  validate: bool = True
+
+  async def __aenter__(self) -> Self:
+    await self.client.__aenter__()
+    return self
+
+  async def __aexit__(self, exc_type, exc_value, traceback):
+    await self.client.__aexit__(exc_type, exc_value, traceback)
+
+  async def request(self, payload: Mapping[str, Any]) -> Any:
+    return await self.client.request(payload)

typed_hyperliquid-1.2.4/src/hyperliquid/core/endpoint/stream.py

@@ -0,0 +1,77 @@
+"""Base endpoint class for stream endpoints -- backs `streams`, the venue's only
+channel-subscription surface.
+
+No `authed_subscribe`: every Hyperliquid channel, public or user-scoped, subscribes with
+a plain `user` address parameter (see `spec/discovery.md`'s Authentication section) --
+there is no channel that additionally requires a wallet signature to open.
+
+Not frozen, for the same reason as `endpoint/rpc.py`: `Streams` composes ~20 single-method
+mixins via multiple inheritance rather than nested `cached_property` children, and
+`dataclasses` requires frozen-ness to agree across that whole chain.
+"""
+
+from typing_extensions import Any, Callable, Protocol, Self
+from dataclasses import dataclass
+
+from typed_core.util import StreamManager
+
+
+class StreamClient(Protocol):
+  """Structural interface a transport implements to back a `StreamEndpoint`.
+
+  `params` is `Any`, not `Mapping[str, Any]`: the concrete transport (`SocketClient`,
+  shared with `info`/`exchange`) subscribes through `typed_core.ws.StreamsRpc`, whose own
+  `params` is a specific `TypedDict` rather than an arbitrary mapping -- a `TypedDict`
+  accepts a stricter set of values than `Mapping[str, Any]`, so typing this any narrower
+  here would make that real implementation fail Protocol conformance.
+  """
+
+  def subscribe(
+    self,
+    channel: str,
+    params: Any = None,
+    *,
+    request_channel: str | None = None,
+    message_key: Callable[[Any], str] | None = None,
+  ) -> StreamManager[Any, Any, Any]:
+    """Subscribe to a channel, optionally separating request and message channels.
+
+    `message_key`: for channels shared across multiple concurrent subscriptions (e.g.
+    `l2Book`, tagged identically for every coin), a function deriving the local
+    subscription key from an incoming notification.
+    """
+    ...
+
+  async def __aenter__(self) -> Self: ...
+
+  async def __aexit__(self, exc_type, exc_value, traceback): ...
+
+
+@dataclass(kw_only=True)
+class StreamEndpoint:
+  """Base class for stream endpoints."""
+
+  client: StreamClient
+  validate: bool = True
+
+  async def __aenter__(self) -> Self:
+    await self.client.__aenter__()
+    return self
+
+  async def __aexit__(self, exc_type, exc_value, traceback):
+    await self.client.__aexit__(exc_type, exc_value, traceback)
+
+  def subscribe(
+    self,
+    channel: str,
+    params: Any = None,
+    *,
+    request_channel: str | None = None,
+    message_key: Callable[[Any], str] | None = None,
+  ) -> StreamManager[Any, Any, Any]:
+    return self.client.subscribe(
+      channel,
+      params,
+      request_channel=request_channel,
+      message_key=message_key,
+    )

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

@@ -0,0 +1,22 @@
+from typed_core.exceptions import (
+  Error,
+  NetworkError,
+  ValidationError,
+  ApiError,
+  BadRequest,
+  AuthError,
+  RateLimited,
+  LogicError,
+)
+
+
+__all__ = [
+  'Error',
+  'NetworkError',
+  'ValidationError',
+  'ApiError',
+  'BadRequest',
+  'AuthError',
+  'RateLimited',
+  'LogicError',
+]

typed_hyperliquid-1.2.4/src/hyperliquid/core/types.py

@@ -0,0 +1,15 @@
+"""Hyperliquid's wire timestamp: milliseconds since the Unix epoch, UTC. Threaded through
+nonce generation (`timestamp.now()`, used by every signed exchange action) and available
+for response fields that adopt `Timestamp` instead of a bare `int`.
+"""
+
+from typing_extensions import Annotated
+from datetime import datetime, timezone
+from pydantic import BeforeValidator
+
+from typed_core.times import EpochConverter
+
+timestamp = EpochConverter.milliseconds(tz=timezone.utc)
+
+Timestamp = Annotated[datetime, BeforeValidator(timestamp.parse)]
+"""A timestamp field, to use directly in a response `TypedDict`'s annotations."""

typed_hyperliquid-1.2.4/src/hyperliquid/core/urls.py

@@ -0,0 +1,19 @@
+"""Hyperliquid network domains, and the per-transport URL resolution every surface
+shares: `info` and `exchange` (HTTP or the shared WebSocket connection) and `streams`
+(WebSocket only) all key off the same mainnet/testnet domain.
+"""
+
+HYPERLIQUID_MAINNET = 'api.hyperliquid.xyz'
+HYPERLIQUID_TESTNET = 'api.hyperliquid-testnet.xyz'
+
+
+def http_base_url(mainnet: bool = True) -> str:
+  """Resolve the HTTP API root shared by `info` and `exchange`."""
+  domain = HYPERLIQUID_MAINNET if mainnet else HYPERLIQUID_TESTNET
+  return f'https://{domain}'
+
+
+def ws_url(mainnet: bool = True) -> str:
+  """Resolve the WebSocket URL shared by `info`, `exchange`, and `streams`."""
+  domain = HYPERLIQUID_MAINNET if mainnet else HYPERLIQUID_TESTNET
+  return f'wss://{domain}/ws'

typed_hyperliquid-1.2.4/src/hyperliquid/core/ws/__init__.py

@@ -0,0 +1,3 @@
+from .client import SocketClient
+
+__all__ = ['SocketClient']