hyperliquid-python-sdk

The Problem

The SDK provides complete Hyperliquid API trading functionality but suffers from architectural complexity that makes changes high-risk. A single module (hyperliquid/utils/__init__.py) is depended on by 40 other modules, and two files exceed 1,000 lines of code each. Duplicated logic appears across 13 example files, and four files exhibit indentation depth of 8 levels, creating cognitive load for anyone modifying the flow.

What This Does

The Hyperliquid Python SDK enables programmatic trading against the Hyperliquid exchange. It wraps the exchange's REST and WebSocket APIs, handling order placement, user state retrieval, position management, and WebSocket subscription updates. The core exchange logic lives in hyperliquid/exchange.py (60 functions, 1 class), which defines order construction, signature generation, and price calculation. State queries route through hyperliquid/info.py (45 functions), which makes outbound network calls to fetch user positions, order books, and funding rates. Signature construction is centralized in hyperliquid/utils/signing.py (34 functions), which is imported by 11 other modules. Forty-six example files demonstrate usage, ranging from basic order placement to multi-sig user abstraction and EVM block indexing.

How It Is Wired

Execution begins at examples/basic_adding.py:222 (main entry point), which reaches 118 functions and is called from 1 call site. The most frequent internal calls are get_timestamp_ms (46 callers), _post_action (43), sign_l1_action (41), and post (40). The primary outbound paths are main -> subscribe (network via self.ws.send) and setup -> user_state -> post (network via self.session.post). The hub module hyperliquid/utils/__init__.py has an instability of 0 but is imported by 40 modules, meaning changes there have blast-radius effects across the entire codebase. Two files—hyperliquid/exchange.py (1,131 lines) and hyperliquid/info.py—are oversized, and 50 repeated 6-line blocks appear across 13 example files, indicating duplicated logic that should be extracted into shared helpers.

How To Use It

Setup: Install via Poetry:

make install

Or pip:

pip install hyperliquid-python-sdk

Configuration: Copy the example config and fill in keys:

cp examples/config.json.example examples/config.json
vim examples/config.json

The config file expects account_address (public key) and secret_key (private key). Set skip_ws=True in the Info constructor if WebSocket connections are unnecessary.

Running it: Execute an example:

python examples/basic_order.py

The README also documents running make test to execute the 26 test files.

Real-World Use

A typical workflow involves querying user state, placing an order, and subscribing to order book updates. For example:

from hyperliquid.info import Info
from hyperliquid.utils import constants

info = Info(constants.TESTNET_API_URL, skip_ws=True)
state = info.user_state("0xcd5051944f780a621ee62e39e493c489668acf4d")
print(state)

This fetches on-chain user data via a single network call. To place an order, the caller constructs an order wire, signs it via hyperliquid/utils/signing, and posts it through hyperliquid/exchange.post. WebSocket subscriptions for live order book updates follow the path main -> subscribe, which sends a WS message and begins polling.

Code Health & Issues

  • HIGH - Pin third-party GitHub Actions to commit SHA: .github/workflows declares snok/install-poetry@v1, which can shift if the tag moves, potentially executing unvetted code with repository secrets.
  • MEDIUM - Declare least-privilege GITHUB_TOKEN permissions: 2 workflows have no permissions declaration, so the token inherits repository defaults and could push commits or mint releases.
  • MEDIUM - Enable Dependabot or Renovate: only 1 manifest exists with no configured update bot; published advisories remain unpatched without automated dependency updates.
  • MEDIUM - Gate pull requests on dependency vulnerability scan: no dependency scan is present in CI; a known-vulnerable package could merge before manual audit.
  • LOW - Set timeout-minutes on workflow jobs: 2 jobs declare no timeout, allowing wedged steps to run to the six-hour platform default.

The Bottom Line

This SDK is functionally complete for Hyperliquid trading but requires discipline to maintain. The highly interconnected module graph and outsized files mean changes ripple widely; the Action pinning and Dependabot gaps are the most urgent SDLC fixes. Teams already using Hyperliquid will find the Python surface familiar, but new contributors should budget time to untangle the nesting and duplicated logic before extending the codebase.