All builder guides

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.

Last verified: November 17, 2026 Markdown version Example code

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 perpsHIP-3 perps
Market nameBTCxyz:NVDA
dex field in info requests"" (empty) or absent"xyz"
Asset id in an orderIndex in meta100000 + 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

python
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:

IndexnamefullName
0""Validator-operated perps
1xyzXYZ
2flxFelix Exchange
3vntlVentuals
4hynaHyENA
5kmMarkets by Kinetiq
6abcdABCDEx
7cashdreamcash
8paraParagon
9mktsMarkets By Kinetiq
10ioEntropyIO

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.

python
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 10

meta["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:

python
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.

python
state = info.user_state("0xYourMainAccount", dex="xyz")   # positions on the xyz dex

Fields 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.

FieldMeaning
maxLeverageThe maximum leverage. It is often lower than on the main perps.
onlyIsolatedIf true, the market does not allow cross margin.
marginModestrictIsolated or noCross. Both mean that the position uses isolated margin.
growthModeIf enabled, the market is in growth mode, which lowers its fees.
isDelistedIf 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:

python
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_meta
  • dex_index is the position of the dex in the perpDexs list. xyz is 1.
  • index_in_meta is the position of the market in meta["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.

python
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 modeCollateral for HIP-3 positions
Unified accountOne balance for each asset. The USDC balance backs validator-operated perps, XYZ perps and USDC spot.
Portfolio marginOne 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:

python
# 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:

python
info.post("/info", {"type": "userAbstraction", "user": "0xYourMainAccount"})

Checklist for a HIP-3 bot

  1. Read perpDexs and meta for each dex at startup.
  2. Skip markets where isDelisted is true.
  3. Use the full dex:COIN name in every call.
  4. Pass dex in every info request about positions, orders or prices.
  5. Check maxLeverage, onlyIsolated and marginMode of the market.
  6. 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.

bash
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-only

The 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

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