Hyperliquid bot builder reference
Trade HIP-3 Markets Through the Hyperliquid API
How HIP-3 market names such as xyz:NVDA work in the Hyperliquid API: the dex field, perp dex list, asset ids, SDK setup, isolated margin and collateral.
HIP-3 markets are perpetual markets that builders deploy on Hyperliquid, such as stocks, indices, commodities and pre-IPO companies. They use the same API as BTC and ETH perps, with three differences: the market name, the dex field and the asset id.
The three differences
| Validator-operated perps | HIP-3 perps | |
|---|---|---|
| Market name | BTC | xyz:NVDA |
dex field in info requests | "" (empty) or absent | "xyz" |
| Asset id in an order | Index in meta | 100000 + dex_index * 10000 + index |
A HIP-3 market is always named {dex}:{coin}. The part before the colon is the short name of the perp dex that lists the market.
List the perp dexs
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.MAINNET_API_URL, skip_ws=True)
dexs = info.perp_dexs()The same request without the SDK is a POST to https://api.hyperliquid.xyz/info with the body {"type": "perpDexs"}.
The response is a list. The first entry is null. It stands for the validator-operated dex, which has the empty name "". Each other entry has name, fullName, deployer and more fields.
On November 17, 2026, mainnet had these perp dexs:
| Index | name | fullName |
|---|---|---|
| 0 | "" | Validator-operated perps |
| 1 | xyz | XYZ |
| 2 | flx | Felix Exchange |
| 3 | vntl | Ventuals |
| 4 | hyna | HyENA |
| 5 | km | Markets by Kinetiq |
| 6 | abcd | ABCDEx |
| 7 | cash | dreamcash |
| 8 | para | Paragon |
| 9 | mkts | Markets By Kinetiq |
| 10 | io | EntropyIO |
The list changes when builders deploy new dexs. Read it from the API. Do not hard-code it.
Read markets and prices on one dex
Every info request that reads perp state accepts a dex field. Without it, the request returns data for the validator-operated dex only.
meta, contexts = info.post("/info", {"type": "metaAndAssetCtxs", "dex": "xyz"})
for asset, ctx in zip(meta["universe"], contexts):
print(asset["name"], ctx["markPx"], ctx["funding"], asset["maxLeverage"])
# xyz:XYZ100 27131.0 0.00000625 30
# xyz:TSLA 381.0 0.00000625 20
# xyz:NVDA 159.66 0.00000625 10meta["universe"] and contexts have the same order. ctx["funding"] is the hourly funding rate.
A common mistake is to call allMids without dex and then look for xyz:NVDA in the result. It is not there. Ask for the dex:
mids = info.all_mids(dex="xyz") # {"xyz:AAPL": "350.475", ...}These SDK methods take a dex argument: meta, all_mids, user_state, open_orders and frontend_open_orders.
state = info.user_state("0xYourMainAccount", dex="xyz") # positions on the xyz dexFields that HIP-3 markets add
Each asset in the meta response of a HIP-3 dex can have more fields than a BTC or ETH asset.
| Field | Meaning |
|---|---|
maxLeverage | The maximum leverage. It is often lower than on the main perps. |
onlyIsolated | If true, the market does not allow cross margin. |
marginMode | strictIsolated or noCross. Both mean that the position uses isolated margin. |
growthMode | If enabled, the market is in growth mode, which lowers its fees. |
isDelisted | If true, the market is closed. Do not send orders to it. |
collateralToken (in meta) | Index of the token that the dex uses as collateral. 0 is USDC. |
Many HIP-3 markets allow isolated margin only. For these markets, set isolated leverage before the first order:
exchange.update_leverage(5, "xyz:NVDA", is_cross=False)Compute the asset id
An order identifies its market with a number, not with a name. For a HIP-3 market:
asset_id = 100000 + dex_index * 10000 + index_in_metadex_indexis the position of the dex in theperpDexslist.xyzis 1.index_in_metais the position of the market inmeta["universe"]for that dex.
xyz:NVDA is at index 2 on dex 1, so its asset id is 100000 + 1 * 10000 + 2 = 110002.
For comparison, a validator-operated perp uses its index in meta (BTC is 0), and a spot pair uses 10000 + index.
Let the SDK do the mapping
Pass perp_dexs when you create the clients. The SDK then accepts HIP-3 names in the normal methods and computes the asset ids for you.
from eth_account import Account
from hyperliquid.exchange import Exchange
DEXS = ["", "xyz"] # "" is the validator-operated dex
info = Info(constants.MAINNET_API_URL, skip_ws=True, perp_dexs=DEXS)
info.name_to_asset("xyz:NVDA") # 110002
exchange = Exchange(
Account.from_key("0x..."),
constants.MAINNET_API_URL,
account_address="0xYourMainAccount",
perp_dexs=DEXS,
)
result = exchange.order("xyz:NVDA", True, 0.1, 150.0, {"limit": {"tif": "Gtc"}})Without perp_dexs, the SDK knows only the validator-operated markets, and xyz:NVDA raises a KeyError.
The price and size precision rules are the same as for other perps. See Place a Hyperliquid order in Python.
Collateral
Where the margin for a HIP-3 position comes from depends on the account mode.
| Account mode | Collateral for HIP-3 positions |
|---|---|
| Unified account | One balance for each asset. The USDC balance backs validator-operated perps, XYZ perps and USDC spot. |
| Portfolio margin | One portfolio across the eligible assets. |
| Standard (manual) | Each perp dex has its own balance. You move collateral to the dex before you trade on it. |
In standard mode, move collateral with the sendAsset action. In the SDK:
# Move 100 USDC from the main perp balance to the xyz dex.
exchange.send_asset("0xYourMainAccount", "", "xyz", "USDC", 100.0)The arguments are: destination address, source dex, destination dex, token, amount. Use "" for the validator-operated dex and "spot" for the spot balance. Only the collateral token of a dex can move to or from that dex.
The main wallet must sign send_asset. An Exchange client that signs with an API wallet cannot call it.
For API users in unified account or portfolio margin mode, balances and holds are in the spot clearinghouse state. The per-dex user_state balances are not meaningful in those modes.
Read the current mode of an account with:
info.post("/info", {"type": "userAbstraction", "user": "0xYourMainAccount"})Checklist for a HIP-3 bot
- Read
perpDexsandmetafor each dex at startup. - Skip markets where
isDelistedis true. - Use the full
dex:COINname in every call. - Pass
dexin every info request about positions, orders or prices. - Check
maxLeverage,onlyIsolatedandmarginModeof the market. - Know your account mode, so you know where the collateral is.
Run a bot on a HIP-3 market
The three open-source bots in hyperliquid-trading-bots accept HIP-3 names. The shared client reads the dex from the name and passes dex and perp_dexs for you.
python3 strategies/ma_crossover/bot.py --symbol xyz:NVDA --fast 10 --slow 30 --size 0.1
python3 strategies/grid_bot/bot.py --symbol xyz:GOLD --levels 5 --spacing 0.3 --size 0.01
python3 strategies/funding_arb/bot.py --dex xyz --scan-onlyThe data paths of the bots are tested against the live API. Order placement on HIP-3 markets is not yet tested with real funds, so start with the smallest size.
Runnable example
examples/02_hip3_markets.py lists the perp dexs, and the markets, prices, funding and asset ids of one dex. It needs no key.
Live data
HIPERWIRE shows current price, funding and open interest for HIP-3 markets on the screener. The same data is available as JSON at https://hiperwire.io/api/screener/live.
Sources
- Asset IDs, Hyperliquid docs
- Exchange endpoint, Hyperliquid docs, for
sendAsset - Account abstraction modes, Hyperliquid docs
- basic_send_asset.py, hyperliquid-python-sdk
- The dex list, the market fields and the asset ids were read from the live mainnet API on November 17, 2026.
More builder guides
- Place a Hyperliquid Order in PythonConnect the Hyperliquid Python SDK, round price and size correctly, place a limit or market order, read the result and cancel. Runs on testnet first.
- Hyperliquid API Wallets (Agent Wallets)What a Hyperliquid API wallet can and cannot do, how to create and use one, which address to query, nonce rules and why a wallet stops working.
- Hyperliquid API Rate LimitsThe Hyperliquid IP limit of 1200 weight each minute, the weight of each request, the address limit of 1 request for each 1 USDC traded, and WebSocket and open-order limits.
- Hyperliquid API Errors and FixesEach Hyperliquid API error message with its cause and fix: tick size, minimum order value, insufficient margin, API wallet does not exist, open interest cap and more.
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