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

- Canonical URL: https://hiperwire.io/build/hyperliquid-hip3-api
- Last verified: November 17, 2026
- Publisher: HIPERWIRE (https://hiperwire.io). Not affiliated with Hyperliquid.

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

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

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

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

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

```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](https://hiperwire.io/build/hyperliquid-python-place-order).

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

```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](https://github.com/atlasdetitan/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](https://github.com/atlasdetitan/hyperliquid-trading-bots/blob/master/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](https://hiperwire.io/metrics). The same data is available as JSON at `https://hiperwire.io/api/screener/live`.

## Sources

- [Asset IDs](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids), Hyperliquid docs
- [Exchange endpoint](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint), Hyperliquid docs, for `sendAsset`
- [Account abstraction modes](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/account-abstraction-modes), Hyperliquid docs
- [basic_send_asset.py](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/examples/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.
