Getting started with the Hyperliquid Python SDK

What you are actually setting up

Three things, and it is worth naming them before touching a terminal, because the confusion between them is the whole difficulty.

Your main wallet is the account. It holds the funds and it is the address everything is recorded against.

An API wallet is an agent it authorises. It signs orders. It cannot withdraw.

The SDK is a Python wrapper around the signed HTTP interface. It does not do anything you could not do with requests and a signing library; it just saves you implementing the signature scheme.

Install and configure

1. Install the package

   pip install hyperliquid-python-sdk. It is the reference implementation, maintained in the hyperliquid-dex organisation on GitHub.

   You should see hyperliquid-python-sdk available in your environment

2. Generate an API wallet in the app

   Do this rather than putting your main private key in a file. The agent can trade and cannot withdraw, so the worst case if the file leaks is bounded.

   Approving the agent is an on-chain action signed by your main wallet, exactly like the Establish Connection step when you first connected.

   You should see a private key for an agent authorised on your account

3. Fill in the config with the two different addresses

   The secret_key is the API wallet’s private key. The account_address is your main wallet’s public key.

   That asymmetry is the single most common first-attempt failure, and the README calls it out explicitly for the same reason.

   You should see a config the SDK can both sign with and query with

4. Read something before you write anything

   Construct Info and query mids or a book. This needs no signature at all, so if it works, your network path and your endpoint choice are both fine, and any later failure is a signing problem rather than a connectivity one.

   You should see live market data printed from the info endpoint

5. Place one small order with Exchange

   Use the real app to confirm it arrived. Seeing your own programmatic order in the interface is the moment the setup is actually verified.

   You should see an order visible in the app's open orders panel

The two classes

Info is the read side. Market metadata, mids, books, candles, an address’s positions and fills. It needs no key. Constructed with an API URL and, if you do not want a WebSocket, skip_ws=True.

Exchange is the write side. Orders, cancels, leverage changes, transfers. It signs every request with the key you configured.

Keeping them separate in your own code is a good habit for the same reason the API separates them: the read path is harmless and the write path is not, and a bug in the first should never be able to become an action in the second.

What breaks on the first attempt

Empty data from every query. The account_address is the API wallet’s rather than the master’s. Query by the master address; sign with the agent.

Orders rejected for size. Below the $10.00 minimum notional, or not aligned to the market’s tick and lot sizes. Both come from the market metadata rather than being global.

Rate limited quickly. Usually a polling loop over the book. Subscribe over the WebSocket instead. The limits, and why they are shaped that way.

Nonce errors. Actions are ordered by nonce per agent. Two processes signing with the same agent will collide, and the fix is one agent per process rather than clever retry logic.

Everything works, then stops after a redeploy. A deregistered agent whose address you reused. Generate a new one — the documentation warns that pruned nonce state makes reuse a replay risk.

From working code to a working strategy

The SDK gets you to a placed order in an afternoon. The distance from there to something worth running is mostly not code.

Order type discipline. Use post-only when you mean to be a maker, and reduce-only on every exit. Both prevent whole categories of expensive accident, and both are one flag. The full list.

Size against the book, not against your balance. A strategy that ignores depth pays slippage that dwarfs the fee difference it was optimising.

Decide what happens when the process dies. Resting orders keep working without you. That is either a feature or a hazard, and it should be a decision.

Running a bot, and what to think about first covers the rest of that list.

Where to go next

The API itself — endpoints, the agent model and the rate limits — and the order types you will be sending through it.