Hyperliquid Python SDK for API Trading and Account Queries

What hyperliquid-python-sdk Handles

hyperliquid-python-sdk targets applications that exchange data or transactions with the Hyperliquid API through Python. It is aimed at developers building account dashboards, automated order clients, account-management tools, and services that need SDK access rather than a separate graphical trading application. The README describes the package specifically as an SDK for Hyperliquid API trading with Python.

The repository shows a broad action surface through its examples. They cover market and limit orders, order modification and scheduled cancellation, spot orders, leverage adjustment, transfers, asset sends, staking, vaults, sub-accounts, referral settings, multisig conversion, recovery, builder-deployed perpetual DEX orders, and builder fees. That list is more useful than a broad feature label because it identifies concrete workflows that have dedicated example files.

The package can also read account information. The README demonstrates importing `Info` and `constants`, constructing an information client against `constants.TESTNET_API_URL`, disabling its WebSocket connection with `skip_ws=True`, and requesting the state of a named account. This makes the SDK relevant to read-only applications as well as transaction-producing clients.

The documented security boundary matters. The configuration contains both `account_address` and `secret_key`. Examples therefore operate in a context where private key custody is part of deployment design. The README also describes API Wallet support, but it requires a distinction: `secret_key` may belong to the API wallet, while `account_address` must remain the public key of the main wallet. An implementation that collapses those identities can construct a different authorization model from the one described by the project.

Python Client Structure and Request Flow

The repository layout separates the installed package, examples, tests, API material, and development configuration. In `pyproject.toml`, the Poetry configuration includes the `hyperliquid` package directory. The README directs developers to `examples/` for more complete usage, while `tests/` contains the test suite. This is a library layout rather than a standalone trading application.

The demonstrated request path begins with a Python import from `hyperliquid.info`, followed by an `Info` instance created from a URL in `hyperliquid.utils.constants`. Calling `info.user_state(...)` returns a Python object representing the account state, which the example prints. The public method accepts an account address, so the immediate operation separates the queried account from the configured local signing identity.

The package declares `requests` and `websocket-client` as dependencies. `requests` supports the repository's HTTP communication path, while `websocket-client` relates to its streaming capability. The `skip_ws=True` argument in the README example explicitly avoids the WebSocket path for that invocation. Repository examples cover trading and account operations beyond this single query, but the README does not document every class, request schema, retry policy, timeout, or response model. Developers should inspect the relevant example and implementation rather than infer all such behavior from the top-level description.

The console entry point is registered as `hyperliquid-python-sdk = hyperliquid.__main__:app`. Its presence confirms that the package includes a command-line entry module, although the README does not document its commands or claim that it replaces using the Python API. For normal SDK integration, the installation target is the importable `hyperliquid` package and its examples.

Installing the Package and Running an Account Query

The README gives a direct installation command for users who want the published package. Run it in the Python environment used by the application, then import the package from application code.

pip install hyperliquid-python-sdk

The published project version in `pyproject.toml` is `0.24.0`. The package metadata sets Python `^3.9`, which permits Python 3.9 and later compatible 3.x releases under Poetry's constraint syntax. The metadata lists classifiers through Python 3.13. Repository development has a stricter expectation: the contribution instructions require Python 3.10 exactly and state that Poetry v2 is not supported.

The following public, read-only example creates an `Info` client against the documented testnet URL, skips WebSocket setup, and requests a user state. It does not require a private-key configuration because the shown call contains no local signing operation.

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

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

The README says this prints the returned user state. It does not provide a sample response, so application code should not be built around an invented fixed value. For repository examples that submit transactions, the documented setup begins by copying and editing the example configuration.

cp examples/config.json.example examples/config.json
vim examples/config.json
python examples/basic_order.py

Set `account_address` to the public key and `secret_key` to the private key, following the README's account identity instructions. Running `basic_order.py` is a transaction-capable example, so its appropriateness depends on the environment and permissions associated with those credentials. The README does not say that this sequence places a testnet order by default, so the example and configuration should be reviewed before execution.

API Wallet Configuration and Key Boundaries

The optional API Wallet flow is not equivalent to replacing both configuration fields with the API wallet's own identifiers. According to the README, users generate and authorize a new API private key through the Hyperliquid application, then put that API wallet's private key in `secret_key`. The `account_address` field must still contain the main wallet's public key.

That identity split is the main operational constraint in the configuration instructions. A service account may sign an action on behalf of a main account without becoming the account whose public key identifies the trading context. Code that selects credentials from environment variables or a secret manager still needs to preserve those roles. The repository's `examples/config.json` is presented as the expected configuration location, while `examples/example_utils.py` shows how examples load it.

The README does not document whether the package accepts credentials directly through every client constructor, how signatures are created, or how signing errors are surfaced. It also does not describe secret rotation, revocation, or a recovery workflow beyond the named `examples/basic_recover_user.py`. Those omissions matter for production use because a successful API call does not prove that key management, rotation, and incident handling have been designed.

Using a file-backed `secret_key` also creates a local security responsibility outside the SDK's functional API. The README does not prescribe file permissions, environment variable names, or secret-store integration. It should not be interpreted as recommending a particular custody mechanism. The concrete requirement is narrower: preserve the documented distinction between main-wallet public identity and API-wallet private signing material, and keep the unedited credential file out of source control according to the repository's own `.gitignore` and operational policy.

Direct API Clients and SDK Constraints

A direct client built with `requests` and `websocket-client` is a real alternative for a team that already owns protocol knowledge and wants minimal SDK behavior between its application and Hyperliquid. Those exact libraries are declared dependencies of hyperliquid-python-sdk, but the README does not state that its internal modules can be bypassed or that both libraries alone are sufficient to reproduce every signed request.

The approach differs in responsibility. A direct HTTP client would require the team to understand request URLs, payload encoding, signing, error responses, and market identifiers without relying on the SDK's examples and utility modules. For streaming features, the team would also manage the WebSocket lifecycle directly. hyperliquid-python-sdk instead supplies Hyperliquid-oriented classes, constants, configuration examples, and workflow samples, reducing the need to infer those details from the protocol surface.

Direct integration may suit an application with strict dependency control or existing Hyperliquid protocol abstractions. It is a poor substitute when the team only needs the documented account query or order examples and has little signing expertise. The SDK is the stronger starting point in that case.

A GUI exchange client is another practical alternative for manual order entry, but it does not serve the same software boundary. It offers little direct reuse inside Python services. The relevant comparison is therefore between the SDK and a programmatically controlled HTTP or WebSocket client, not between automation and a desktop interface. Before replacing the SDK with direct calls, verify that every required operation has documented request and response handling.

Release Cadence, Licensing, and Upgrade Cost

The package metadata classifies hyperliquid-python-sdk as `Development Status :: 3 - Alpha`, despite a sequence of Semantic Version releases. Version `0.24.0` is recorded in `pyproject.toml` and was released on 2026-06-04. Earlier listed releases are `0.23.0` on 2026-04-14 and `0.22.0` on 2026-02-04. The project says it follows Semantic Versions and uses Release Drafter to assemble categorized release notes.

The repository is not archived, and its last push was on 2026-06-04. Those facts do not erase the Alpha classification or guarantee compatibility for an unattended trading deployment. They indicate recent repository activity relative to the listed development history, but adoption still depends on release notes and the specific API surface being used.

Upgrading can be operationally costly because a trading client may combine authentication, account state, order creation, cancellation, transfers, and market metadata. The repository provides `make test`, pre-commit checks, mypy type installation, safety checks, and lockfile commands for contributors. Consumer teams that modify calls should review each GitHub release for Features, Fixes & Refactoring, Breaking Changes, Documentation, and Dependencies updates, because the project labels those categories.

The MIT license permits use, modification, distribution, and sublicensing under its conditions, while the software is provided without warranty. That is a licensing summary, not legal advice. The package's copyright and license notice should remain intact when redistributing modified copies. The README does not document a compatibility window, deprecation policy, migration guide for every release, or rollback procedure, so none should be assumed.

Editorial conclusion

Python teams trading through the documented API can adopt version 0.24.0 after checking account-key handling, Python compatibility, and the relevant example. It is a poor fit for users who need stable production classification, a point-and-click terminal, or documented rollback procedures. The first adoption check should confirm that the SDK version, API Wallet configuration, target environment, and order example match the intended workflow.

Frequently asked questions

Official sources

1. hyperliquid-dex/hyperliquid-python-sdk on GitHub
2. Issues
3. License: MIT
4. README
5. Releases