Hyperliquid Provider

Market Lab integrates Hyperliquid as a standalone exchange and execution venue. The current integration connects only to Hyperliquid testnet native perpetuals. It does not connect to mainnet, spot markets, or HIP-3 deployments.

Use hyperliquid directly as the exchange or venue name:

mlab markets --exchange hyperliquid --refresh
mlab source orderbook --exchange hyperliquid --symbol BTC/USDT --depth 20
mlab trade long BTC/USDT --venue hyperliquid --margin 10 --dry-run

Do not add --provider. That flag is reserved for routed data providers such as MMT.

Quick Setup

Install the current native-perpetual market catalog:

mlab markets --exchange hyperliquid --refresh

Public market data works without a wallet:

mlab health --exchange hyperliquid
mlab source orderbook --exchange hyperliquid --symbol BTC/USDT --depth 20

Authorize execution only when you are ready to trade on testnet:

mlab auth set hyperliquid
mlab auth status

The command asks for the testnet main-wallet private key through a hidden prompt. Market Lab uses it once to authorize a newly generated API wallet, then stores only the main address and API-wallet key in the operating system keychain. The main-wallet private key is never stored.

Preview the complete trade plan before submitting anything:

mlab trade long BTC/USDT \
  --venue hyperliquid \
  --margin 100 \
  --leverage 5 \
  --dry-run

Market Catalog

Refresh, list, and inspect the installed snapshot:

mlab markets --exchange hyperliquid --refresh
mlab markets --exchange hyperliquid
mlab markets --exchange hyperliquid --symbol BTC/USDT

The refresh reads Hyperliquid's current native perpetual universe, filters markets that are no longer trading, validates the response, and atomically replaces:

~/.market-lab/markets/hyperliquid-markets.json

Commands without --refresh use this local file. Market existence, market type, lot size, leverage limit, and supported order behavior can therefore be checked without adding a network request to the execution path.

The catalog stores both the native coin and Market Lab symbol. For example, Hyperliquid's native BTC perpetual is exposed as BTC/USDT inside Market Lab. Common BTC/USD and BTC/USDC input forms resolve to the same installed market. Hyperliquid settles its native perpetuals in USDC; the Market Lab symbol is a normalized command identifier, not a claim that the venue settles in USDT.

The displayed tick is a useful catalog snapshot. Hyperliquid also applies price precision rules relative to the submitted price, so Market Lab validates and rounds every live order again at the adapter boundary.

Market Data

All commands in this section are public and use --exchange hyperliquid without --provider.

Orderbook

Hyperliquid exposes at most 20 levels per side through this integration:

mlab source orderbook \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --depth 20

mlab source orderbook \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --depth 20 \
  --stream \
  --output jsonl

Historical orderbook inspection and replay are not available.

Candles

Historical candle range:

mlab source candles \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --timeframe 60 \
  --from 1780307559000 \
  --to 1780523645000 \
  --output json

Native live candle stream:

mlab source candles \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --timeframe 60 \
  --stream \
  --output jsonl

Supported native timeframes, in seconds, are 60, 180, 300, 900, 1800, 3600, 7200, 14400, 28800, 43200, 86400, 259200, 604800, and 2592000.

Live scripts are different: Market Lab consumes Hyperliquid trades and can construct custom second-based candle intervals locally. It omits the first partial bucket after startup so the first candle represents a complete interval. Backtests use the native historical intervals listed above.

Open Interest

Direct Hyperliquid open interest is current or live. It has no historical range or timeframe:

mlab source oi --exchange hyperliquid --symbol BTC/USDT
mlab source oi --exchange hyperliquid --symbol BTC/USDT --stream --output jsonl

Use an MMT selector such as oi@hyperliquid@mmt:timeframe=60 when normalized historical OI is required for a script backtest or OIWAP trajectory.

Volume

Volume bars use Hyperliquid's native candle data:

mlab source volumes \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --timeframe 60 \
  --from 1780307559000 \
  --to 1780523645000 \
  --output json

mlab source volumes \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --timeframe 60 \
  --stream \
  --output jsonl

Volume Delta

Live volume delta is derived from the public trades feed. It is stream-only and accepts no timeframe, range, or bucket:

mlab source vd \
  --exchange hyperliquid \
  --symbol BTC/USDT \
  --stream \
  --output jsonl

Statistics and Funding

Hyperliquid statistics currently use the 1d period. A live statistics stream requires a symbol:

mlab source stats --exchange hyperliquid --period 1d --output json
mlab source stats --exchange hyperliquid --symbol BTC/USDT --period 1d --stream --output jsonl

Funding is current or live:

mlab source funding --exchange hyperliquid --symbol BTC/USDT
mlab source funding --exchange hyperliquid --symbol BTC/USDT --stream --output jsonl

Authentication

Authorize an API Wallet

mlab auth set hyperliquid

Market Lab:

1. Reads the main wallet only from a hidden one-time prompt.
2. Generates a random API wallet locally.
3. Authorizes it as the account's unnamed testnet agent.
4. Stores the main address and API-wallet private key in the OS keychain under the testnet credential.
5. Uses the API wallet for later order, cancellation, and leverage signatures.

Hyperliquid account queries must use the main address, while signed actions use the authorized API wallet. Market Lab keeps that distinction inside the venue adapter.

Replace the Agent

If the stored agent is invalid or must be rotated:

mlab auth set hyperliquid --reauthorize

Hyperliquid permits one unnamed API wallet at a time. Authorizing the replacement invalidates the previously authorized unnamed wallet.

Remove the Credential

mlab auth remove hyperliquid

Removal asks for the main wallet again, authorizes a fresh replacement so the stored agent is no longer active, then removes the local keychain credential. Status output includes public identifiers only.

Execution

Hyperliquid is never selected implicitly. Pass --venue hyperliquid to every CLI order, account command, strategy, bot, or executable script job.

mlab trade long BTC/USDT \
  --venue hyperliquid \
  --margin 100 \
  --leverage 5 \
  --dry-run

mlab trade short BTC/USDT \
  --venue hyperliquid \
  --size 0.01 \
  --type limit \
  --price 65000 \
  --tif alo \
  --dry-run

Current execution behavior:

• leverage is whole-number cross leverage and is updated before a non-reduce-only order
• limit orders support GTC, IOC, and post-only ALO
• a Market Lab market order becomes a limit IOC with a 50 bps price guard around the reference price
• reduce-only is sent natively
• stop-loss and take-profit use Hyperliquid normalTpsl grouping and reduce-only market triggers
• Hyperliquid does not provide a native OCO guarantee here, so one trigger is not documented as cancelling its sibling
• venue order IDs are Hyperliquid numeric order IDs rather than Market Lab-generated deterministic IDs

Account and order management use the same explicit venue:

mlab positions --venue hyperliquid
mlab orders --venue hyperliquid
mlab fills --venue hyperliquid
mlab cancel BTC/USDT <ORDER_ID> --venue hyperliquid --dry-run
mlab close BTC/USDT --venue hyperliquid --dry-run

The current adapter operates on the authenticated main account. Vault and subaccount execution are not exposed.

Signed exchange actions are sent to Hyperliquid's HTTP exchange endpoint. Public market state and private order/fill lifecycle events are tracked over WebSocket. All signing, nonce generation, keychain access, and job ownership stay inside mlabd.

Scripts

Use direct Hyperliquid selectors exactly as they appear in the command:

mlab script run ./scripts/strategy.js \
  --symbol BTC/USDT \
  --source candles@hyperliquid:timeframe=5 \
  --source orderbook@hyperliquid:depth=20

Inside the script:

const candles = history.source('candles@hyperliquid')
const book = history.source('orderbook@hyperliquid', 0)

Add the execution venue only when the script should be allowed to trade:

mlab script run ./scripts/strategy.js \
  --symbol BTC/USDT \
  --source candles@hyperliquid:timeframe=5 \
  --source orderbook@hyperliquid:depth=20 \
  --venue hyperliquid

The source and venue remain independent. A script may read candles@binancef@mmt and execute on Hyperliquid, or read direct Hyperliquid data and execute somewhere else.

Strategies and Bots

The built-in execution strategies and market-making bots use the same venue abstraction:

mlab strategy run twap BTC/USDT \
  --venue hyperliquid \
  --side buy \
  --margin 100 \
  --duration 300 \
  --interval 60 \
  --dry-run

mlab strategy run vwap BTC/USDT \
  --venue hyperliquid \
  --side buy \
  --margin 100 \
  --duration 3600 \
  --volume-sources hyperliquid,binancef@mmt \
  --dry-run

mlab bot run mid-price BTC/USDT \
  --venue hyperliquid \
  --margin 100 \
  --leverage 5 \
  --duration 3600 \
  --spread-bps 6 \
  --dry-run

OIWAP may execute on Hyperliquid, but its historical and live OI trajectory sources remain normalized MMT selectors such as hyperliquid@mmt. The execution venue's trades, orderbook, and fills still constrain actual order size and timing.

Current Boundaries

The integration deliberately excludes:

• Hyperliquid mainnet
• spot markets
• HIP-3 markets
• vault and subaccount execution
• historical direct open interest
• historical orderbook inspection or replay
• native OCO guarantees for paired TP/SL triggers

Official References

• Hyperliquid API
• Info endpoint
• Exchange endpoint
• WebSocket subscriptions
• Nonces and API wallets