All builder guides

Hyperliquid bot builder reference

Place a Hyperliquid Order in Python

Connect the Hyperliquid Python SDK, round price and size correctly, place a limit or market order, read the result and cancel. Runs on testnet first.

Last verified: November 17, 2026 Markdown version Example code

This guide shows how to place, read and cancel a Hyperliquid order with the official Python SDK. Every code block runs as written against SDK version 0.24.0.

What you need

Install the SDK

bash
python3 -m pip install hyperliquid-python-sdk

Connect

Use testnet until your code works. Testnet and mainnet have different URLs, different funds and different API wallets.

python
from eth_account import Account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

API_URL = constants.TESTNET_API_URL      # constants.MAINNET_API_URL for real funds
wallet = Account.from_key("0x...")       # private key of the API wallet
ACCOUNT = "0x..."                        # address of the main account

info = Info(API_URL, skip_ws=True)
exchange = Exchange(wallet, API_URL, account_address=ACCOUNT)

Info reads data and needs no key. Exchange signs actions. account_address is the account that the API wallet trades for.

NetworkAPI URL
Mainnethttps://api.hyperliquid.xyz
Testnethttps://api.hyperliquid-testnet.xyz

Round the price and the size

Hyperliquid rejects an order whose price or size has too much precision. The rules are:

  • A price can have at most 5 significant figures.
  • A perp price can have at most 6 - szDecimals decimal places. A spot price can have at most 8 - szDecimals.
  • An integer price is always valid.
  • A size is rounded to szDecimals decimal places.

szDecimals is part of each asset in the meta response. For example, ETH has szDecimals of 4, so 3456.78 is not valid (6 significant figures) and 3456.8 is valid.

python
sz_decimals = {a["name"]: a["szDecimals"] for a in info.meta()["universe"]}

def round_price(px: float, coin: str) -> float:
    return round(float(f"{px:.5g}"), 6 - sz_decimals[coin])

def round_size(sz: float, coin: str) -> float:
    return round(sz, sz_decimals[coin])

Size is in units of the asset, not in USD. An order for 0.01 ETH is 0.01 ETH. The minimum order value is $10.

Place a limit order

python
mid = float(info.all_mids()["ETH"])
price = round_price(mid * 0.95, "ETH")     # 5% below the market, so it rests
size = round_size(15 / price, "ETH")       # about $15

result = exchange.order("ETH", True, size, price, {"limit": {"tif": "Gtc"}})

The arguments are: coin, is_buy, size, limit price, order type. The time-in-force values are:

tifMeaning
GtcGood until canceled. The order rests on the book.
IocImmediate or cancel. The part that does not fill is canceled.
AloAdd liquidity only (post-only). The order is canceled if it would match immediately.

Pass reduce_only=True to make sure an order can only reduce a position.

Read the result

Hyperliquid answers with HTTP 200 when it rejects an action. The SDK does not raise an exception. You must check two levels.

python
if result["status"] != "ok":
    raise RuntimeError(f"Action rejected: {result['response']}")

status = result["response"]["data"]["statuses"][0]
if "error" in status:
    raise RuntimeError(f"Order rejected: {status['error']}")
elif "resting" in status:
    oid = status["resting"]["oid"]
elif "filled" in status:
    oid = status["filled"]["oid"]          # also has totalSz and avgPx
  • The top level is the whole action. A wrong key gives {"status": "err", "response": "User or API Wallet 0x... does not exist."}.
  • statuses has one entry for each order in the request. Each entry is resting, filled or error.

See Hyperliquid API errors and fixes for each error string.

Place a market order

The API has no separate market order. The SDK method market_open sends an Ioc limit order at a price 5% through the mid price. You can change the slippage argument.

python
result = exchange.market_open("ETH", True, 0.01, slippage=0.01)

market_close("ETH") closes the whole position in the same way.

Cancel an order

python
exchange.cancel("ETH", oid)

To cancel many orders in one request, use bulk_cancel. One request with many orders uses less of your IP rate limit. See Hyperliquid API rate limits.

Common mistakes

  • The size is in USD. It must be in asset units.
  • The price is not rounded. The error is Price must be divisible by tick size.
  • The code checks only for exceptions. A rejected order does not raise. Check status and statuses.
  • The API wallet address is used to read the account. Read positions and orders with the main account address.
  • The mainnet key is used on testnet. Each network has its own API wallets.

Runnable example

examples/03_place_order.py places a post-only order, reads each status and cancels the order. It uses testnet when HL_NETWORK=testnet is set.

Sources

More builder guides

New to Hyperliquid?

The referral code HIPERWIRE gives a new account 4% off trading fees on its first $25M of volume. It also funds this reference. HIPERWIRE is independent and is not affiliated with Hyperliquid.

Open Hyperliquid with code HIPERWIRE